From 719e82801079fa0cccb53330f8ceba48e147fdc9 Mon Sep 17 00:00:00 2001 From: qiansc Date: Tue, 10 Nov 2026 09:56:48 +0000 Subject: [PATCH] feat: report every production citation problem at once, keep moved evidence, and unblock stuck routes - Production-stage submissions report all citation problems, keep or follow repeated earlier citations, and support --preview; capture-gap placeholders cannot be cited. - Synced blocks without access are permission gaps; same-revision refreshes save located downgrades; checkout checks scale with size; long fetches and clones run while they progress. - prepare-current re-checks failed sources and returns the next Route; navigation-only changes after delivery route to version and build; version record waits for Review; clearer out-of-scope and unowned-path messages; source remove ignores registry-derived declarations; no EPIPE crash. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 16 ++++ .../manuals/guides/knowledge-updates.md | 11 ++- .../manuals/guides/lark-resources.md | 11 ++- .../resources/procedures/knowledge-updates.md | 11 ++- .../procedures/production-stage-files.md | 8 +- .../approvedRevisionReferences.test.ts | 28 ++++++ .../__tests__/checkoutMatchesCommit.test.ts | 26 ++++++ .../src/__tests__/cliEpipe.test.ts | 12 +++ .../src/__tests__/gitProgress.test.ts | 59 +++++++++++++ .../src/__tests__/larkCaptureRefresh.test.ts | 32 ++++++- .../__tests__/larkResourcePermissions.test.ts | 22 +++++ .../__tests__/navigationVersionRoute.test.ts | 59 +++++++++++++ .../src/__tests__/nextRoute.test.ts | 11 +++ .../__tests__/productionArticleEdits.test.ts | 69 ++++++++++++++- .../productionKnownTasks.integration.test.ts | 21 +++++ ...productionMixedSources.integration.test.ts | 8 +- .../productionSubmission.integration.test.ts | 32 ++++++- .../projectPendingSourceUpdate.test.ts | 5 +- .../projectSourceRemovalV0611.test.ts | 58 ++++++++++++ .../versionRecordReviewGuard.test.ts | 34 +++++++ packages/context-cli/src/cli.ts | 5 ++ .../src/commands/actionCommands.ts | 7 +- .../src/commands/documentRevisionCommands.ts | 15 +--- .../context-cli/src/commands/nextRoute.ts | 22 +++++ .../src/commands/versionCommands.ts | 17 ++++ packages/context-cli/src/lib/gitProgress.ts | 77 ++++++++++++++++ .../src/lib/larkResourceCommand.ts | 13 +++ .../src/lib/larkResourceMaterialization.ts | 4 +- .../src/project/approvedRevisionReferences.ts | 4 +- .../project/articleReferenceObservation.ts | 9 +- .../src/project/articleSourceReader.ts | 27 ++++-- .../src/project/documentCaptureLark.ts | 11 ++- .../src/project/knowledgeUpdate.ts | 13 ++- .../src/project/productionAction.ts | 13 ++- .../src/project/productionArticle.ts | 88 ++++++++++++++++--- .../src/project/productionKnownTasks.ts | 19 +++- .../project/productionPlanningMaterials.ts | 37 ++++++-- .../src/project/productionSubmission.ts | 63 +++++++++++-- .../src/project/repoContentPrefetch.ts | 14 ++- .../src/project/repoSourceRecovery.ts | 26 +++--- .../context-cli/src/project/sourceRemoval.ts | 41 +++++++-- packages/context-cli/src/project/status.ts | 38 +++++++- .../src/project/submittedSourceLocator.ts | 15 ++++ .../src/project/workflow/workflowFacts.ts | 3 +- .../context/docs/guides/knowledge-updates.md | 11 ++- .../context/docs/guides/lark-resources.md | 11 ++- packages/context/src/sources.ts | 13 ++- 47 files changed, 1022 insertions(+), 127 deletions(-) create mode 100644 packages/context-cli/src/__tests__/checkoutMatchesCommit.test.ts create mode 100644 packages/context-cli/src/__tests__/cliEpipe.test.ts create mode 100644 packages/context-cli/src/__tests__/gitProgress.test.ts create mode 100644 packages/context-cli/src/__tests__/navigationVersionRoute.test.ts create mode 100644 packages/context-cli/src/__tests__/nextRoute.test.ts create mode 100644 packages/context-cli/src/__tests__/versionRecordReviewGuard.test.ts create mode 100644 packages/context-cli/src/commands/nextRoute.ts create mode 100644 packages/context-cli/src/lib/gitProgress.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index da883965..d9360059 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,22 @@ All notable changes to Context are documented here. +## Unreleased + +- Production-stage article submissions report every citation problem of the article at once, one entry per fragment. A citation that repeats an earlier citation's lines keeps that evidence: it stays when the text is unchanged, follows the text when it moved to one unique place, and is reported with its state (changed, ambiguous or unreadable) and, when available, where the text now is; the current text at the old lines is never signed in its place. +- `context action complete-current --preview` also checks production-stage article files: every problem of every task in one run, without saving anything. Plans and report decisions have no preview. +- A citation of a source file the source does not own lists the files it does own. A citation of a source outside the task names the requirement in `src/indexers.yaml` to extend and every task (this one and those depending on it) that the plan amendment must replace. +- A captured document's capture gap (`> Resource unavailable: ...`) cannot be cited, in revisions and in production; citations of the captured text around it are accepted, including a table row whose other cells were captured. +- A synced block whose source document the capturing identity cannot open (Lark code 3380004) is a permission gap like an unreadable whiteboard: the document is saved and the gap listed. Permission gaps say how to close them: request the app scope at https://open.larkoffice.com/app, or ask the document's owner to share it. +- Refreshing an unchanged Lark revision no longer refuses to save when a resource captured before is now a permission gap, a missing source or an image preview; the snapshot is saved and the result lists each downgrade. Other resource failures still keep the old snapshot, and an unreadable body never replaces it. +- Production planning checks whether a repository checkout matches its registered commit with a time limit that grows with the number of files, without taking Git's index lock, and retries once; a check that cannot finish is reported as unchecked instead of making the source unavailable. +- Long Git fetches and clones (source recovery, content download, commit fetch) continue while Git's progress shows more objects or more received bytes (warnings and repeated lines do not count), stop after about five minutes without progress, and stop and report after 30 minutes; previously they stopped after a fixed two minutes. Failure reasons name the source and hide credentials. +- When a production stage has unavailable sources, `context action prepare-current` checks them again instead of reusing the failed result, and the refresh error's next command keeps the `--input` file. `prepare-current` output returns the next Route, keeping the command's `--managed` mode. +- `context version record` refuses while drafts still await review, unless the workflow itself reached version recording (partial delivery). +- After delivery, a knowledge-map-only change (`context task adjust` with `knowledge_map`) routes to recording a patch version and building, instead of asking to resume production, also when the change or its version was committed first or a note beside the workspace (such as a TODO file) changed with it. The knowledge updates guide describes how to merge unpublished intermediate versions into one entry. +- `context source remove` no longer counts the sources and capture phases that the project builds from the source registry as references to the source; declarations written in the project's own files, in any module, still block removal. +- Output piped to a reader that stops early (`context status | head`) no longer crashes the CLI with `EPIPE`. + ## 0.7.96 - 2026-11-09 - `context plugin install --local` for Claude and Cursor also installs the `resources/` folders that the installed commands link to (for example the routine update and version alignment references); previously those links were broken in local installs. Global installs were not affected. Like skills, an existing folder is replaced only if an earlier local install wrote it unchanged. diff --git a/packages/context-cli/context-workflow/resources/manuals/guides/knowledge-updates.md b/packages/context-cli/context-workflow/resources/manuals/guides/knowledge-updates.md index 0e9f33b7..fe2dea63 100644 --- a/packages/context-cli/context-workflow/resources/manuals/guides/knowledge-updates.md +++ b/packages/context-cli/context-workflow/resources/manuals/guides/knowledge-updates.md @@ -193,6 +193,13 @@ untagged version updates that description without changing its version or conten checkpoint. No additional flag is needed. If this session already published the version, record a new version instead: the CLI protects tagged records but cannot infer whether an untagged version was published by another tool. +To merge several unpublished intermediate versions into one entry, restore only +the version files (`package.json` version, `CHANGELOG.md`, `changelog.yaml`) to +the last published version and keep every knowledge change. Then run `version +inspect --base --format json` and record one entry with +the returned digest and the same commit as `base_ref`. Never rewrite a version +already merged into the remote default branch (`merged_to`) or tagged; there is +no squash command. Publication belongs to the installed distribution tool. Record remote receipts in its configuration or the existing work summary, separately for each target. A successful authorized commit/tag identifies the delivered source; never create @@ -212,7 +219,9 @@ entry retains its stable key, parent, title and order; optional targets use article identity and section key. The current structure preview supplies those identities. Read the persistent `src/knowledge-map.yaml`; use `expected_revision: null` only when no knowledge map exists. -After adjustment, follow status to rebuild affected packages. This changes the +After adjustment, follow status to rebuild affected packages; once delivery has +finished, the Route records a patch version (`navigation` trigger) and builds, +without resuming production. This changes the reading organization without capturing sources or rewriting approved prose. Do not directly edit generated package navigation or use titles as identities. diff --git a/packages/context-cli/context-workflow/resources/manuals/guides/lark-resources.md b/packages/context-cli/context-workflow/resources/manuals/guides/lark-resources.md index 64a7087b..216fcf59 100644 --- a/packages/context-cli/context-workflow/resources/manuals/guides/lark-resources.md +++ b/packages/context-cli/context-workflow/resources/manuals/guides/lark-resources.md @@ -89,8 +89,15 @@ an explicit permission denial (including HTTP 403) for an embedded resource, Con `document.resource.permission-denied`, keeps the stable resource identity in the audit layer, renders the same unavailable-resource notice, and continues with a warning. Explicit missing-scope and access-denied resource responses are -likewise recorded without changing identity. Transient network errors, malformed -payloads, and unclassified failures still block capture. Reference-only +likewise recorded without changing identity, as is a synced block whose source +document the identity cannot open. Such gaps are listed in the capture result and +cannot be cited. To close one, request the missing app scope for the app at +https://open.larkoffice.com/app, or ask the document's owner to share it with +the capturing identity, then capture again. Transient network errors, malformed +payloads, and unclassified failures still block capture. When a refresh of an +unchanged revision turns a previously captured resource into such a gap or a +preview, the new snapshot is saved and the result lists the downgrade; a blocking +failure keeps the old snapshot, and a body that cannot be read never replaces it. Reference-only resources remain explicit in the capture report. Unknown non-empty XML blocks stay auditable in the raw XML and receive a warning; the CLI does not infer their meaning. diff --git a/packages/context-cli/context-workflow/resources/procedures/knowledge-updates.md b/packages/context-cli/context-workflow/resources/procedures/knowledge-updates.md index 1262613a..79b46435 100644 --- a/packages/context-cli/context-workflow/resources/procedures/knowledge-updates.md +++ b/packages/context-cli/context-workflow/resources/procedures/knowledge-updates.md @@ -193,6 +193,13 @@ untagged version updates that description without changing its version or conten checkpoint. No additional flag is needed. If this session already published the version, record a new version instead: the CLI protects tagged records but cannot infer whether an untagged version was published by another tool. +To merge several unpublished intermediate versions into one entry, restore only +the version files (`package.json` version, `CHANGELOG.md`, `changelog.yaml`) to +the last published version and keep every knowledge change. Then run `version +inspect --base --format json` and record one entry with +the returned digest and the same commit as `base_ref`. Never rewrite a version +already merged into the remote default branch (`merged_to`) or tagged; there is +no squash command. Publication belongs to the installed distribution tool. Record remote receipts in its configuration or the existing work summary, separately for each target. A successful authorized commit/tag identifies the delivered source; never create @@ -212,7 +219,9 @@ entry retains its stable key, parent, title and order; optional targets use article identity and section key. The current structure preview supplies those identities. Read the persistent `src/knowledge-map.yaml`; use `expected_revision: null` only when no knowledge map exists. -After adjustment, follow status to rebuild affected packages. This changes the +After adjustment, follow status to rebuild affected packages; once delivery has +finished, the Route records a patch version (`navigation` trigger) and builds, +without resuming production. This changes the reading organization without capturing sources or rewriting approved prose. Do not directly edit generated package navigation or use titles as identities. diff --git a/packages/context-cli/context-workflow/resources/procedures/production-stage-files.md b/packages/context-cli/context-workflow/resources/procedures/production-stage-files.md index eff1e441..69474fde 100644 --- a/packages/context-cli/context-workflow/resources/procedures/production-stage-files.md +++ b/packages/context-cli/context-workflow/resources/procedures/production-stage-files.md @@ -62,7 +62,9 @@ Write results under the returned Agent directory. All submission paths are relative to `.tmp/agent-work/production-stages//`, even when the manifest is in `submissions/`. They are never relative to `.tmp/context-runtime/` or to the manifest location. Each task lists the complete workspace-relative Markdown and reference output paths. Copy the CLI's submission template, keep completed tasks only, and keep each task's prefilled `input`. Submit the manifest using the returned command. -Do not edit submitted files until the command returns. +To check article files first, append `--preview` to that command: it reports +every problem of every task at once and saves nothing. Plans and report decisions +have no preview. Do not edit submitted files until the command returns. A complete article uses `content` (Markdown) and `references` (YAML/JSON). Markdown has reader-facing title and description frontmatter, followed by the @@ -70,7 +72,9 @@ complete article with stable `context:section` markers. References contain `sections`, each with its matching `id` and `references` list. A reference is `source_ref` plus `locator: {path, start_line, end_line}` from actual authorized text. CLI computes source digests. A fragment may cite at most five distinct -source files and eight regions; an article may have multiple fragments. +source files and eight regions; an article may have multiple fragments. A line +`> Resource unavailable: ...` in a captured document marks a capture gap, not +evidence: cite the captured lines around it, never the gap. When prose names a file, directory or Skill from a cited repository, write its exact repository-relative path, or the unique name of its directory such as a diff --git a/packages/context-cli/src/__tests__/approvedRevisionReferences.test.ts b/packages/context-cli/src/__tests__/approvedRevisionReferences.test.ts index ee75083b..314c7fa0 100644 --- a/packages/context-cli/src/__tests__/approvedRevisionReferences.test.ts +++ b/packages/context-cli/src/__tests__/approvedRevisionReferences.test.ts @@ -338,5 +338,33 @@ test("an incomplete captured document blocks an in-scope stale citation and remi const reminders: ReferenceReminder[] = []; expect(await prepareRevisionReferences({ ...input, onReminder: item => reminders.push(item) })).toEqual([{ id: "s", references: [cited] }]); expect(reminders).toEqual([expect.objectContaining({ state: "unavailable", reason: "source-capture-incomplete" })]); + // A path the document does not own names the document's files. + const notOwned = await prepareRevisionReferences({ ...input, edits: [{ section_id: "s", references: [ + { source_ref: "file:product-docs", locator: { path: "assets/diagram.png", start_line: 1, end_line: 1 } }] }] }).catch(value => value); + expect(notOwned.message).toContain("Source path assets/diagram.png is not owned by the registered document file:product-docs; cite one of its files: intro.md"); } finally { await rm(root, { recursive: true, force: true }); } }, 60_000); + +test("a revision may cite captured text but not a capture-gap placeholder", async () => { + const root = await mkdtemp(join(tmpdir(), "revision-capture-gap-")); + const sourceRef = "note:20260912/source.md"; + try { + await mkdir(join(root, "sources/note/20260912"), { recursive: true }); + await writeFile(join(root, "sources/note/20260912/source.md"), + "Main rule\n> Resource unavailable: Synced block (synced_block; permission denied). \n"); + const submit = (locator: { start_line: number; end_line: number } | { quote: string }) => prepareRevisionReferences({ projectRoot: root, sourceRefs: [sourceRef], + previous: [], sectionIds: ["s"], edits: [{ section_id: "s", references: [{ source_ref: sourceRef, locator: { path: "source.md", ...locator } }] }] }); + expect((await submit({ start_line: 1, end_line: 1 }))[0]!.references).toHaveLength(1); + await expect(submit({ start_line: 1, end_line: 2 })).rejects.toThrow("source.md:2 is a capture gap"); + await expect(submit({ quote: "Synced block" })).rejects.toThrow("is a capture gap"); + // In a table, a row with captured cells besides the gap stays citable; a row of gaps does not. + await writeFile(join(root, "sources/note/20260912/source.md"), [ + "| 官号IM招募 | 私信主播 | > Resource unavailable: Whiteboard (whiteboard; export permission denied). |", + "| | > Resource unavailable: Whiteboard (whiteboard; export permission denied).

|", ""].join("\n")); + expect((await submit({ start_line: 1, end_line: 1 }))[0]!.references).toHaveLength(1); + await expect(submit({ start_line: 2, end_line: 2 })).rejects.toThrow("source.md:2 is a capture gap"); + // Prose that only starts like a placeholder is ordinary text. + await writeFile(join(root, "sources/note/20260912/source.md"), "> Resource unavailable: explained in the guide\n"); + expect((await submit({ start_line: 1, end_line: 1 }))[0]!.references).toHaveLength(1); + } finally { await rm(root, { recursive: true, force: true }); } +}); diff --git a/packages/context-cli/src/__tests__/checkoutMatchesCommit.test.ts b/packages/context-cli/src/__tests__/checkoutMatchesCommit.test.ts new file mode 100644 index 00000000..f274eb16 --- /dev/null +++ b/packages/context-cli/src/__tests__/checkoutMatchesCommit.test.ts @@ -0,0 +1,26 @@ +import { afterEach, expect, test } from "bun:test"; +import { execFileSync } from "node:child_process"; +import { mkdtemp, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { checkoutMatchesCommit } from "../project/productionPlanningMaterials.js"; + +const roots: string[] = []; +afterEach(async () => { for (const root of roots.splice(0)) await rm(root, { recursive: true, force: true }); }); + +test("only a real difference counts as differs; a failed check is unchecked, not a missing source", async () => { + const root = await mkdtemp(join(tmpdir(), "checkout-check-")); roots.push(root); + const git = (...args: string[]) => execFileSync("git", ["-C", root, ...args], { encoding: "utf8" }).trim(); + git("init", "-q"); git("config", "user.email", "t@example.test"); git("config", "user.name", "T"); + await writeFile(join(root, "a.txt"), "one\n"); + git("add", "a.txt"); git("commit", "-qm", "init"); + const ref = git("rev-parse", "HEAD"); + expect(await checkoutMatchesCommit(root, ref, 1)).toEqual({ state: "same" }); + await writeFile(join(root, "a.txt"), "changed\n"); + expect(await checkoutMatchesCommit(root, ref, 1)).toEqual({ state: "differs" }); + // A broken index makes git fail for another reason: retried, then reported as unchecked. + await writeFile(join(root, ".git/index"), "not an index"); + const unchecked = await checkoutMatchesCommit(root, ref, 1); + expect(unchecked.state).toBe("unchecked"); + expect("reason" in unchecked && unchecked.reason.length).toBeGreaterThan(0); +}); diff --git a/packages/context-cli/src/__tests__/cliEpipe.test.ts b/packages/context-cli/src/__tests__/cliEpipe.test.ts new file mode 100644 index 00000000..2282b416 --- /dev/null +++ b/packages/context-cli/src/__tests__/cliEpipe.test.ts @@ -0,0 +1,12 @@ +import { expect, test } from "bun:test"; +import { execFileSync } from "node:child_process"; +import { resolve } from "node:path"; + +// Requires a current build (bun run build). +test("output piped to a reader that closes early does not crash the CLI", () => { + const cli = resolve(import.meta.dir, "../../dist/cli.js"); + // `true` exits without reading, so the CLI's write hits a closed pipe; stderr stays readable. + const out = execFileSync("bash", ["-c", `{ node '${cli}' task adjust --schema --format json | true; echo "exit=\${PIPESTATUS[0]}"; } 2>&1`], { encoding: "utf8" }); + expect(out).not.toContain("EPIPE"); + expect(out.trim()).toEndWith("exit=0"); +}); diff --git a/packages/context-cli/src/__tests__/gitProgress.test.ts b/packages/context-cli/src/__tests__/gitProgress.test.ts new file mode 100644 index 00000000..36a63488 --- /dev/null +++ b/packages/context-cli/src/__tests__/gitProgress.test.ts @@ -0,0 +1,59 @@ +import { afterEach, expect, test } from "bun:test"; +import { chmod, mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"; +import { join, resolve } from "node:path"; +import { GitProgressError, runGitWithProgress } from "../lib/gitProgress.js"; + +const roots: string[] = []; +afterEach(async () => { for (const root of roots.splice(0)) await rm(root, { recursive: true, force: true }); }); +/** A stand-in git: prints `steps` progress lines `delay` ms apart, optionally repeating one line. */ +async function fakeGit(script: string) { + // Package-local: some environments mount the system temp directory noexec. + await mkdir(resolve(".tmp"), { recursive: true }); + const root = await mkdtemp(join(resolve(".tmp"), "git-progress-")); roots.push(root); + const bin = join(root, "git"); + await writeFile(bin, `#!/usr/bin/env node\nconst args = process.argv.slice(2);\n${script}\n`); + await chmod(bin, 0o755); + return bin; +} + +test("a slow fetch that keeps progressing finishes; stdout stays clean", async () => { + const bin = await fakeGit(`if (!args.includes("--progress")) process.exit(9); +let i = 0; const t = setInterval(() => { process.stderr.write("Receiving objects: " + (++i) + "% (" + i + "/10)\\r"); + if (i === 10) { clearInterval(t); process.stdout.write("done\\n"); } }, 150);`); + expect(await runGitWithProgress(["fetch", "origin"], { bin, label: "git fetch", idleMs: 500, limitMs: 10_000 })).toBe("done\n"); +}); + +test("repeating the same line is not progress", async () => { + const bin = await fakeGit(`setInterval(() => process.stderr.write("Receiving objects: 40% (4/10)\\r"), 100);`); + const error = await runGitWithProgress(["fetch", "origin"], { bin, label: "git fetch", idleMs: 600, limitMs: 10_000 }).catch(value => value); + expect(error).toBeInstanceOf(GitProgressError); + expect(error.kind).toBe("no-progress"); + expect(error.message).toContain("Receiving objects: 40% (4/10)"); +}); + +test("a large object still downloading is progress, though the object count stays", async () => { + const bin = await fakeGit(`let i = 0; const t = setInterval(() => { process.stderr.write("Receiving objects: 40% (4/10), " + (++i * 0.5).toFixed(2) + " MiB | 1.00 MiB/s\\r"); + if (i === 12) { clearInterval(t); process.stdout.write("done\\n"); } }, 100);`); + expect(await runGitWithProgress(["fetch", "origin"], { bin, label: "git fetch", idleMs: 400, limitMs: 10_000 })).toBe("done\n"); +}); + +test("warnings between unchanged progress lines are not progress", async () => { + const bin = await fakeGit(`let i = 0; setInterval(() => process.stderr.write(++i % 2 ? "Receiving objects: 40% (4/10)\\r" : "warning: retry 1\\n"), 100);`); + const error = await runGitWithProgress(["fetch", "origin"], { bin, label: "git fetch", idleMs: 600, limitMs: 3_000 }).catch(value => value); + expect(error.kind).toBe("no-progress"); +}); + +test("the total limit is reported separately from no progress, without credentials", async () => { + const bin = await fakeGit(`let i = 0; setInterval(() => process.stderr.write("Receiving objects: " + (++i) + " from https://user:secret@example.test/r.git\\r"), 100);`); + const error = await runGitWithProgress(["clone", "https://user:secret@example.test/r.git", "x"], { bin, label: "git clone", idleMs: 5_000, limitMs: 800 }).catch(value => value); + expect(error.kind).toBe("too-long"); + expect(error.message).toContain("Report this to the user"); + expect(error.message).not.toContain("secret"); +}); + +test("a failing command reports git's error line without credentials", async () => { + const bin = await fakeGit(`process.stderr.write("fatal: could not read from https://token@example.test/r.git\\n"); process.exit(128);`); + const error = await runGitWithProgress(["fetch", "origin"], { bin, label: "git fetch" }).catch(value => value); + expect(error.kind).toBe("failed"); + expect(error.message).toBe("git fetch failed: fatal: could not read from https://example.test/r.git"); +}); diff --git a/packages/context-cli/src/__tests__/larkCaptureRefresh.test.ts b/packages/context-cli/src/__tests__/larkCaptureRefresh.test.ts index 078933d8..5b1d3cde 100644 --- a/packages/context-cli/src/__tests__/larkCaptureRefresh.test.ts +++ b/packages/context-cli/src/__tests__/larkCaptureRefresh.test.ts @@ -214,13 +214,41 @@ test.each(["preview", "reference-only", "existing-preview"])("same-revision capt // Repeating an already degraded representation is not a new downgrade. const repeated = await runCaptureLarkPhase(input); expect(repeated.resource_materialization.items[0]?.reason_code).toBe("document.resource.preview"); + } else if (mode === "preview") { + // A located downgrade is saved and listed, not refused: the main text is still captured. + const saved = await runCaptureLarkPhase(input); + expect(saved.resource_materialization.items[0]).toMatchObject({ status: "materialized", reason_code: "document.resource.preview" }); + expect(saved.diagnostics.join("\n")).toContain("lark.capture.resource-degraded: image"); } else { await expect(runCaptureLarkPhase(input)).rejects.toThrow("existing snapshot was preserved"); expect(await Promise.all(paths.map(path => readFile(join(root, path))))).toEqual(before); revision = "2"; const next = await runCaptureLarkPhase(input); expect(next.snapshot.changed).toBe(true); - expect(next.resource_materialization.items[0]).toMatchObject(mode === "preview" - ? { status: "materialized", reason_code: "document.resource.preview" } : { status: "reference-only" }); + expect(next.resource_materialization.items[0]).toMatchObject({ status: "reference-only" }); } }); + +test("a same-revision refresh keeps the main text when a resource becomes a permission gap", async () => { + const root = await workspace(); let denied = false; + const read: LarkRunner = async (args, options) => { + if (args.includes("--help")) return { stdout: "--api-version string\n--doc-format string", stderr: "", exitCode: 0 }; + if (args.includes("+media-download") || args.includes("+media-preview")) { + if (denied) return { stdout: "", exitCode: 1, + stderr: JSON.stringify({ ok: false, error: { type: "authorization", subtype: "permission_denied", message: "Image access denied" } }) }; + await writeFile(resolve(options!.cwd!, args[args.indexOf("--output") + 1]!), "original image"); + return { stdout: JSON.stringify({ ok: true, data: { saved: true } }), stderr: "", exitCode: 0 }; + } + return { stdout: JSON.stringify({ ok: true, data: { revision_id: "1", document: { + content: 'Guide

Main rule

Diagram', + } } }), stderr: "", exitCode: 0 }; + }; + await runCaptureLarkPhase({ projectRoot: root, phase, larkRunner: read }); + denied = true; + const saved = await runCaptureLarkPhase({ projectRoot: root, phase, larkRunner: read, refreshSources: ["lark:handbook"] }); + expect(saved.resource_materialization.items[0]).toMatchObject({ status: "failed", reason_code: "document.resource.permission-denied" }); + expect(saved.diagnostics.join("\n")).toContain("lark.capture.resource-degraded: image"); + const body = await readFile(join(root, documentPath), "utf8"); + expect(body).toContain("Main rule"); + expect(body).toContain("> Resource unavailable: Diagram"); +}); diff --git a/packages/context-cli/src/__tests__/larkResourcePermissions.test.ts b/packages/context-cli/src/__tests__/larkResourcePermissions.test.ts index 6b2eff91..c1786075 100644 --- a/packages/context-cli/src/__tests__/larkResourcePermissions.test.ts +++ b/packages/context-cli/src/__tests__/larkResourcePermissions.test.ts @@ -126,3 +126,25 @@ test.each(["bad-request", "invalid-json"])("keeps whiteboard raw %s failures vis expect(result.report.status).toBe("error"); expect(result.report.items[0]?.reason_code).toBeUndefined(); }); + +test("a synced block whose source document the identity cannot view is a permission gap, not a capture failure", async () => { + // The error shape recorded by the 1106 capture: docs +fetch fails with API code 3380004. + const denial = `lark-cli docs +fetch failed: ${JSON.stringify({ ok: false, identity: "bot", error: { type: "api", subtype: "unknown", + code: 3380004, message: "No permission to operate on this document: the current user lacks view or edit access." } }, null, 2)}`; + const result = await materializeLarkResources({ + identity: "bot", policy, runner: async () => { throw new Error("no runner call expected"); }, + resources: [{ kind: "synced-reference", locator: "lark:synced:private", attributes: { "src-token": "doc", "src-block-id": "block" } }], + resolveSyncedReference: async () => { throw new LarkCliError(denial, 1, ""); }, + }); + expect(result.report.status).toBe("warning"); + expect(result.report.items[0]).toMatchObject({ status: "failed", reason_code: DOCUMENT_RESOURCE_PERMISSION_DENIED_REASON_CODE }); + expect(result.report.items[0]!.reason).toContain("Ask the document's owner to share it with the capturing identity"); + expect(result.replacements.get("lark:synced:private")).toContain("Resource unavailable:"); + // A missing app scope points to the Open Platform instead. + const scoped = await materializeLarkResources({ + identity: "bot", policy, runner: async () => { throw new Error("no runner call expected"); }, + resources: [{ kind: "synced-reference", locator: "lark:synced:scope", attributes: { "src-token": "doc", "src-block-id": "block" } }], + resolveSyncedReference: async () => { throw new LarkCliError("Document fetch failed", 1, scopeError); }, + }); + expect(scoped.report.items[0]!.reason).toContain("https://open.larkoffice.com/app"); +}); diff --git a/packages/context-cli/src/__tests__/navigationVersionRoute.test.ts b/packages/context-cli/src/__tests__/navigationVersionRoute.test.ts new file mode 100644 index 00000000..de3ace76 --- /dev/null +++ b/packages/context-cli/src/__tests__/navigationVersionRoute.test.ts @@ -0,0 +1,59 @@ +import { afterEach, expect, test } from "bun:test"; +import { execFileSync } from "node:child_process"; +import { rm, writeFile } from "node:fs/promises"; +import { join } from "node:path"; +import { initialRevisionKnowledge } from "./initialRevisionKnowledge.fixture.js"; +import { applyKnowledgeMapUpdate, inspectKnowledgeMap } from "../project/knowledgeMap.js"; +import { collectProjectStatus } from "../project/status.js"; +import { inspectWorkspaceVersion, recordWorkspaceVersion } from "../project/workspaceChangelog.js"; +import { buildProjectPackages } from "../project/packageBuilder.js"; + +const roots: string[] = []; +afterEach(async () => { for (const root of roots.splice(0)) await rm(root, { recursive: true, force: true }); }); + +test("a navigation-only change after delivery routes to version recording and build, not a new task", async () => { + const root = await initialRevisionKnowledge(roots); + const git = (...args: string[]) => execFileSync("git", ["-C", root, "-c", "user.name=t", "-c", "user.email=t@example.com", ...args], { stdio: "ignore" }); + const node = async () => (await collectProjectStatus(root)).workflow.current?.node; + const record = async (version: string, kind: "initial" | "navigation") => recordWorkspaceVersion(root, { version, title: version, + changes: [version], triggers: [{ kind, description: version }], expected_digest: (await inspectWorkspaceVersion(root)).expected_digest }); + git("init", "-q"); git("add", "-A"); git("commit", "-qm", "init"); + await record("0.1.0", "initial"); await buildProjectPackages(root); + git("add", "-A"); git("commit", "-qm", "0.1.0"); + expect(await node()).toBe("reopen-cleared-task"); + const map = await inspectKnowledgeMap(root); + await applyKnowledgeMapUpdate(root, { expected_revision: map.revision, upsert: [{ ...map.entries[0]!, title: "Renamed overview" }], remove: [] }); + expect(await node()).toBe("record-workspace-version"); + await record("0.1.1", "navigation"); + expect(await node()).toBe("build-next"); + await buildProjectPackages(root); + expect(await node()).toBeUndefined(); + git("add", "-A"); git("commit", "-qm", "0.1.1"); + expect(await node()).toBe("reopen-cleared-task"); +}, 60_000); + +test("committing the navigation change before recording or building keeps the route", async () => { + const root = await initialRevisionKnowledge(roots); + const git = (...args: string[]) => execFileSync("git", ["-C", root, "-c", "user.name=t", "-c", "user.email=t@example.com", ...args], { stdio: "ignore" }); + const node = async () => (await collectProjectStatus(root)).workflow.current?.node; + const record = async (version: string, kind: "initial" | "navigation") => recordWorkspaceVersion(root, { version, title: version, + changes: [version], triggers: [{ kind, description: version }], expected_digest: (await inspectWorkspaceVersion(root)).expected_digest }); + git("init", "-q"); git("add", "-A"); git("commit", "-qm", "init"); + await record("0.1.0", "initial"); await buildProjectPackages(root); + git("add", "-A"); git("commit", "-qm", "0.1.0"); + const map = await inspectKnowledgeMap(root); + await applyKnowledgeMapUpdate(root, { expected_revision: map.revision, upsert: [{ ...map.entries[0]!, title: "Renamed overview" }], remove: [] }); + git("add", "-A"); git("commit", "-qm", "navigation"); + // A working note committed beside it does not need production either. + await writeFile(join(root, "TODO.md"), "Follow-ups\n"); + git("add", "-A"); git("commit", "-qm", "note"); + expect(await node()).toBe("record-workspace-version"); + await record("0.1.1", "navigation"); + git("add", "-A"); git("commit", "-qm", "0.1.1"); + expect(await node()).toBe("build-next"); + // Without a local build record (a fresh clone or cleared .tmp), the build is not confirmed either. + await rm(join(root, ".tmp/context-runtime/packages"), { recursive: true, force: true }); + expect(await node()).toBe("build-next"); + await buildProjectPackages(root); + expect(await node()).toBe("reopen-cleared-task"); +}, 60_000); diff --git a/packages/context-cli/src/__tests__/nextRoute.test.ts b/packages/context-cli/src/__tests__/nextRoute.test.ts new file mode 100644 index 00000000..afff55ae --- /dev/null +++ b/packages/context-cli/src/__tests__/nextRoute.test.ts @@ -0,0 +1,11 @@ +import { expect, test } from "bun:test"; +import { Command } from "commander"; +import { nextRouteExecution } from "../commands/nextRoute.js"; + +test("the next Route keeps the running command's managed mode and authorities with the global ones", () => { + const program = new Command().option("--workflow-managed").option("--workflow-authority "); + program.parse(["node", "context", "--workflow-authority", "context.source-read"]); + expect(nextRouteExecution(program, { managed: true, authorities: ["context.package-output"] })) + .toEqual({ managed: true, authorities: ["context.source-read", "context.package-output"] }); + expect(nextRouteExecution(program)).toEqual({ managed: false, authorities: ["context.source-read"] }); +}); diff --git a/packages/context-cli/src/__tests__/productionArticleEdits.test.ts b/packages/context-cli/src/__tests__/productionArticleEdits.test.ts index 09583c29..3ddb2d05 100644 --- a/packages/context-cli/src/__tests__/productionArticleEdits.test.ts +++ b/packages/context-cli/src/__tests__/productionArticleEdits.test.ts @@ -103,7 +103,7 @@ test("a body-only edit cannot silently accept changed retained evidence", async files: { task: task.id, input: task.input, edits: { path: "edits.yaml", text, digest: durableContentDigest(text), bytes: Buffer.byteLength(text), } }, - })).rejects.toThrow("Retained source text changed"); + })).rejects.toThrow("repeats an earlier citation, which is not-found"); }); test("only validated citations grant inherited authority, including repair-draft edits", async () => { @@ -124,7 +124,72 @@ test("only validated citations grant inherited authority, including repair-draft }; expect((await run(base)).source_refs).toEqual([reference.source_ref]); await expect(run()).rejects.toThrow("outside this task"); - await expect(run(base, "Changed evidence\n")).rejects.toThrow("Retained source text changed"); + await expect(run(base, "Changed evidence\n")).rejects.toThrow("repeats an earlier citation, which is not-found"); await expect(run(base, "Source text\n", true)).rejects.toThrow("outside this task"); } finally { await rm(root, { recursive: true, force: true }); } }); + +test("repeated earlier lines keep, follow a unique move, or report why — all fragments at once", async () => { + const cite = (line: number, text: string) => createArticleSourceReference("note:source.md", { path: "source.md", start_line: line, end_line: line }, text); + const old = "Alpha rule\nBeta rule\nGamma rule\nDelta rule\n"; + const trusted: ProductionArticleBase = { + markdown: `---\ntitle: Existing article\ndescription: Existing answer\n---\n\n${wrap("a", "A.")}\n${wrap("b", "B.")}\n${wrap("c", "C.")}\n${wrap("d", "D.")}\n`, + sections: [{ id: "a", references: [cite(1, old)] }, { id: "b", references: [cite(2, old)] }, + { id: "c", references: [cite(3, old)] }, { id: "d", references: [cite(4, old)] }], + }; + const planned = { id: "revision", article_id: "article:existing", path: "architecture/existing.md", question: "Clarify", + sources: [{ scope: "note:source.md", baseline: `sha256:${"a".repeat(64)}` }], + base: `sha256:${"b".repeat(64)}`, batch: "one", after: [], status: "issued" as const }; + const task = { ...planned, input: productionTaskInput(planned) }; + // Every fragment resubmits its earlier lines explicitly, as the 1106 agent did. + const references = YAML.stringify({ sections: trusted.sections.map(section => ({ id: section.id, + references: section.references.map(ref => ({ source_ref: ref.source_ref, locator: ref.locator })) })) }); + const submit = (current: string) => prepareProductionArticle({ projectRoot: ".tmp/unused-production-references", task, + base: trusted, trustedBase: trusted, approvedBaseDigest: null, preview: true, sourceReader: async () => current, + files: { task: task.id, input: task.input, + content: { path: "article.md", text: trusted.markdown, digest: durableContentDigest(trusted.markdown), bytes: Buffer.byteLength(trusted.markdown) }, + references: { path: "references.yaml", text: references, digest: durableContentDigest(references), bytes: Buffer.byteLength(references) } } }); + // a stays, b moved once (a line inserted above), c changed, d now appears twice. + const current = "Alpha rule\nInserted line\nBeta rule\nGamma changed\nDelta rule\nDelta rule\n"; + const error = await submit(current).catch(value => value); + expect(error.detail.problems.map((item: { section: string }) => item.section)).toEqual(["c", "d"]); + expect(error.detail.problems[0].message).toContain("source.md:3-3 repeats an earlier citation, which is not-found"); + expect(error.detail.problems[1].message).toContain("source.md:4-4 repeats an earlier citation, which is ambiguous"); + // With c and d resolved, a keeps its lines and b follows its unique move instead of re-signing line 2. + const candidate = await submit("Alpha rule\nInserted line\nBeta rule\nGamma rule\nDelta rule\n"); + const lines = candidate.indexer_candidate!.sections.map(section => section.references.map(ref => ref.locator.start_line)); + expect(lines).toEqual([[1], [3], [4], [5]]); +}); + +test("captured text is citable, a capture-gap placeholder is not", async () => { + const planned = { id: "check", article_id: "article:existing", path: "architecture/existing.md", question: "Clarify", + sources: [{ scope: "note:source.md", baseline: `sha256:${"a".repeat(64)}` }], + base: `sha256:${"b".repeat(64)}`, batch: "one", after: [], status: "issued" as const }; + const task = { ...planned, input: productionTaskInput(planned) }; + const source = "Main rule\n> Resource unavailable: Synced block (synced_block; permission denied). \nNext rule\n"; + const file = (path: string, text: string) => ({ path, text, bytes: Buffer.byteLength(text), digest: durableContentDigest(text) }); + const submit = (start: number, end: number) => { + const references = YAML.stringify({ sections: [{ id: "a", references: [{ source_ref: "note:source.md", locator: { path: "source.md", start_line: start, end_line: end } }] }, + { id: "b", references: [] }] }); + return prepareProductionArticle({ projectRoot: ".tmp/unused-production-references", task, approvedBaseDigest: null, preview: true, + sourceReader: async () => source, files: { task: task.id, input: task.input, + content: file("content.md", base.markdown), references: file("references.yaml", references) } }); + }; + expect((await submit(1, 1)).source_refs).toEqual(["note:source.md"]); + await expect(submit(1, 3)).rejects.toThrow("source.md:2 is a capture gap"); +}); + +test("an unauthorized source names the requirement to extend and every task the amendment replaces", async () => { + const planned = { id: "revision", article_id: "article:existing", path: "architecture/existing.md", question: "Clarify", + sources: [{ scope: "note:own.md", baseline: `sha256:${"a".repeat(64)}` }], + base: `sha256:${"b".repeat(64)}`, batch: "one", after: [], status: "issued" as const }; + const task = { ...planned, input: productionTaskInput(planned) }; + const file = (path: string, text: string) => ({ path, text, bytes: Buffer.byteLength(text), digest: durableContentDigest(text) }); + const references = YAML.stringify({ sections: [{ id: "a", references: [{ source_ref: "note:source.md", locator: { path: "source.md", start_line: 1, end_line: 1 } }] }, + { id: "b", references: [] }] }); + await expect(prepareProductionArticle({ projectRoot: ".tmp/unused-production-references", task, approvedBaseDigest: null, preview: true, + sourceReader: async () => "Source text\n", authorization: async () => ({ requirements: ["guild"], dependents: ["s2", "s3"] }), + files: { task: task.id, input: task.input, content: file("content.md", base.markdown), references: file("references.yaml", references) } })) + .rejects.toThrow("Cite only note:own.md, or authorize it: add note:source.md to evidence_source_scope of requirement guild in src/indexers.yaml, " + + "then submit a plan amendment whose replaces lists revision, s2, s3 (this task and the tasks that depend on it)"); +}); diff --git a/packages/context-cli/src/__tests__/productionKnownTasks.integration.test.ts b/packages/context-cli/src/__tests__/productionKnownTasks.integration.test.ts index 724d1442..e058626a 100644 --- a/packages/context-cli/src/__tests__/productionKnownTasks.integration.test.ts +++ b/packages/context-cli/src/__tests__/productionKnownTasks.integration.test.ts @@ -72,6 +72,27 @@ test("known 1:1 work reaches the report with one preparation command and no sepa console.info(`Known-task CLI fixture (including one idempotency retry): ${(performance.now() - started).toFixed(0)}ms`); }); +test("rerunning known tasks checks a previously unreadable source again instead of reusing the failure", async () => { + const f = await fixture(); + const { readdir, rename } = await import("node:fs/promises"); + const notes = join(f.root, "sources/note"); + const file = (await readdir(notes, { recursive: true })).find(path => String(path).endsWith("access.md"))!; + await rename(join(notes, file), join(notes, `${file}.away`)); + const command = ["action", "prepare-current", "--revision", f.revision, "--input", f.path, "--format", "json"]; + let failure = ""; + try { await runCliInDir(f.root, command); } + catch (error) { const output = error as { stdout?: string; stderr?: string }; failure = `${output.stdout ?? ""}${output.stderr ?? ""}`; } + expect(failure).toContain("production-planning-refresh-required"); + const stage = (await readProductionStage(f.root))!; + // The next step is the same command with its input, not a refresh that drops it. + expect(failure).toContain(`prepare-current --revision ${stage.id} --input ${f.path}`); + await rename(join(notes, `${file}.away`), join(notes, file)); + const result = JSON.parse(await runCliInDir(f.root, ["action", "prepare-current", "--revision", stage.id, "--input", f.path, "--format", "json"])); + expect((await readProductionStage(f.root))!.planning_complete).toBe(true); + // The output names the next step (the report), so no status check is needed. + expect(result.workflow.current.node).toBe("confirm-production-report"); +}); + test.each(["json", "yaml"] as const)("large file-submission diagnostics remain complete in temporary output (%s)", async format => { const f = await fixture(); await runCliInDir(f.root, ["action", "prepare-current", "--revision", f.revision, "--input", f.path, "--format", "json"]); diff --git a/packages/context-cli/src/__tests__/productionMixedSources.integration.test.ts b/packages/context-cli/src/__tests__/productionMixedSources.integration.test.ts index bd79552f..3ede4c10 100644 --- a/packages/context-cli/src/__tests__/productionMixedSources.integration.test.ts +++ b/packages/context-cli/src/__tests__/productionMixedSources.integration.test.ts @@ -120,7 +120,13 @@ test("code plus two documents share reader topics across skills and batches thro content: "submissions/1.md", references: "submissions/1.refs.yaml" }] })); const invalidRange = await completeProductionSubmission({ projectRoot: root, stage: issued.id, path: "submissions/ready.yaml" }); expect(invalidRange.accepted).toEqual([]); - expect(invalidRange.failed).toMatchObject([{ task: issued.tasks[1]!.id, section: "answer" }]); + // Every citation beyond the file's end is reported, each naming its lines. + expect(invalidRange.failed).toHaveLength(refs[1]!.length); + for (const [index, failure] of invalidRange.failed.entries()) { + const locator = refs[1]![index]!.locator; + expect(failure).toMatchObject({ task: issued.tasks[1]!.id, section: "answer" }); + expect(failure.reason).toContain(`${locator.path}:${locator.start_line}-999: Source region exceeds captured text`); + } expect(await readCandidateRecords(root)).toEqual([retained]); await writeFile(join(agent, "submissions/repair.yaml"), YAML.stringify({ edits: [{ replace: ["answer"], with: [{ id: "answer", references: refs[1] }] }] })); await writeFile(join(agent, "submissions/ready.yaml"), YAML.stringify({ stage: issued.id, diff --git a/packages/context-cli/src/__tests__/productionSubmission.integration.test.ts b/packages/context-cli/src/__tests__/productionSubmission.integration.test.ts index af92217b..cedaf340 100644 --- a/packages/context-cli/src/__tests__/productionSubmission.integration.test.ts +++ b/packages/context-cli/src/__tests__/productionSubmission.integration.test.ts @@ -107,13 +107,40 @@ test.each([ expect((await readProductionStage(f.root))!.tasks[1]!.status).not.toBe("accepted"); }); +test("a production preview checks every task with the submission rules and saves nothing", async () => { + const f = await fixture(); + const secondRefPath = join(f.directory, "two/references.yaml"); + await writeFile(secondRefPath, (await readFile(secondRefPath, "utf8")).replaceAll("end_line: 2", "end_line: 99")); + const { readdir } = await import("node:fs/promises"); + // Every command's transaction recovery may create its empty directory; that is not task data. + const listing = async () => (await readdir(join(f.root, ".tmp"), { recursive: true })) + .filter(path => path !== "context-runtime/transactions").sort(); + const before = { files: await listing(), ledger: await readFile(join(f.root, CANDIDATE_LEDGER_FILE), "utf8").catch(() => ""), + stage: await readProductionStage(f.root) }; + const preview = await completeProductionSubmission({ ...f.input, preview: true }); + expect(preview).toMatchObject({ protocol: "context.production-submission-preview/v1", written: false, ok: ["one"] }); + expect(preview.failed.length).toBeGreaterThan(0); + expect(preview.failed.every(item => item.task === "two" && item.file === "two/references.yaml")).toBe(true); + // No candidate, task state, repair draft or source-region cache was written. + expect(await readFile(join(f.root, CANDIDATE_LEDGER_FILE), "utf8").catch(() => "")).toBe(before.ledger); + expect(await readProductionStage(f.root)).toEqual(before.stage); + expect(await listing()).toEqual(before.files); + // The real submission behaves as before. + const submitted = await completeProductionSubmission(f.input); + expect(submitted.accepted.map(item => item.task)).toEqual(["one"]); + expect(submitted.failed).toEqual(preview.failed); +}); + test("accepts cross-source cross-batch subset, repairs only failures and replays original receipts", async () => { const f = await fixture(); const secondRefPath = join(f.directory, "two/references.yaml"); const correct = await readFile(secondRefPath, "utf8"); await writeFile(secondRefPath, correct.replaceAll("end_line: 2", "end_line: 99")); const first = await completeProductionSubmission(f.input); - expect(first.failed).toMatchObject([{ task: "two", section: "behavior", file: "two/references.yaml" }]); + // Every broken fragment of the task is reported at once, starting with the first. + expect(first.failed[0]).toMatchObject({ task: "two", section: "behavior", file: "two/references.yaml" }); + expect(first.failed.length).toBeGreaterThan(1); + expect(first.failed.every(item => item.task === "two" && item.file === "two/references.yaml")).toBe(true); expect(first.accepted.map(item => item.task)).toEqual(["one"]); expect((await readCandidateRecords(f.root))[0]!.source_refs).toHaveLength(2); const before = (await readProductionStage(f.root))!; @@ -601,7 +628,8 @@ test("a failed new article can repair only one fragment using the fixed temporar await writeFile(join(f.directory, "two/references.yaml"), YAML.stringify(correct).replaceAll("end_line: 2", "end_line: 99")); const first = await completeProductionSubmission(f.input); expect(first.accepted.map(item => item.task)).toEqual(["one"]); - expect(first.failed).toHaveLength(1); + // One entry per broken citation, all in the one failed task's only fragment. + expect(first.failed.every(item => item.task === "two" && item.section === "behavior")).toBe(true); // The Agent-owned original is no longer the fixed rejected input. await writeFile(join(f.directory, "two/article.md"), "Unrelated later draft, not submitted."); await writeFile(join(f.directory, "repair.yaml"), YAML.stringify({ edits: [{ replace: ["behavior"], diff --git a/packages/context-cli/src/__tests__/projectPendingSourceUpdate.test.ts b/packages/context-cli/src/__tests__/projectPendingSourceUpdate.test.ts index 4f8944df..71ff74db 100644 --- a/packages/context-cli/src/__tests__/projectPendingSourceUpdate.test.ts +++ b/packages/context-cli/src/__tests__/projectPendingSourceUpdate.test.ts @@ -108,7 +108,7 @@ test("digest relocation in a shallow checkout confirms moved citations without f expect(update.changed_references).toBeUndefined(); expect(update.candidates).toEqual([]); // File history is not read; only the processed commit's trees are fetched, to list uncited changes. - const fetches = (await readFile(trace, "utf8")).split("\n").filter(line => line.includes("built-in: git fetch --quiet")); + const fetches = (await readFile(trace, "utf8")).split("\n").filter(line => line.includes("built-in: git fetch")); expect(fetches).toHaveLength(1); expect(fetches[0]).toContain(processed); // Only the cited file changed; an incomparable checkout would report an unavailable entry instead. @@ -222,7 +222,8 @@ test("a registered commit that cannot be fetched is tried once per update", asyn const trace = join(root, ".tmp/git-trace.log"); process.env.GIT_TRACE = trace; try { - await expect(beginKnowledgeUpdate(root, undefined, { pending: true })).rejects.toThrow(/could not be fetched\. Check that the registered commit SHA exists/u); + // The reason the fetch failed is part of the message. + await expect(beginKnowledgeUpdate(root, undefined, { pending: true })).rejects.toThrow(/could not be fetched \(git fetch of commit [0-9a-f]{12} failed: .+\)\. Check that the registered commit SHA exists/u); } finally { delete process.env.GIT_TRACE; } expect((await readFile(trace, "utf8")).split("\n").filter(line => line.includes("built-in: git fetch"))).toHaveLength(1); expect(await readKnowledgeUpdate(root)).toBeUndefined(); diff --git a/packages/context-cli/src/__tests__/projectSourceRemovalV0611.test.ts b/packages/context-cli/src/__tests__/projectSourceRemovalV0611.test.ts index 8f5e02e8..9dc24263 100644 --- a/packages/context-cli/src/__tests__/projectSourceRemovalV0611.test.ts +++ b/packages/context-cli/src/__tests__/projectSourceRemovalV0611.test.ts @@ -122,6 +122,64 @@ describe("project source removal", () => { } }); + test("sources the entry builds from the registry are removed without editing the entry", async () => { + const root = await mkdtemp(join(tmpdir(), "ctx-source-remove-derived-")); + try { + const initialized = await initContextProject({ cwd: root, projectDir: "kb", dev: true }); + const docs = join(root, "docs"); + await mkdir(docs, { recursive: true }); + await writeFile(join(docs, "guide.md"), "# Guide\n", "utf8"); + expect((await invokeCliInDir(initialized.projectRoot, [ + "source", "add", "file", "20260811", "--module", "guide", "--local", docs, "--format", "json", + ])).status).toBe(0); + const entry = [ + 'import { fileURLToPath } from "node:url";', + 'import { captureFile, defineProject, loadSourcesRegistry, source } from "@c4a/context";', + 'const registry = await loadSourcesRegistry({ rootDir: fileURLToPath(new URL("../", import.meta.url)) });', + 'const files = registry.files.map(entry => source(entry.name, { type: "file" }));', + "export default defineProject({ sources: files, phases: files.map(item => captureFile({ source: item })), packages: [] });", + "", + ].join("\n"); + await writeFile(join(initialized.projectRoot, "src/index.ts"), entry, "utf8"); + const preview = await invokeCliInDir(initialized.projectRoot, [ + "source", "remove", "20260811/guide", "--format", "json", + ]); + const removed = await invokeCliInDir(initialized.projectRoot, [ + "source", "remove", "20260811/guide", "--yes", "--plan-digest", removalDigest(preview.stdout), "--format", "json", + ]); + expect(removed.status).toBe(0); + expect(await readFile(join(initialized.projectRoot, "sources/file/index.yaml"), "utf8")).not.toContain("guide"); + expect(await readFile(join(initialized.projectRoot, "src/index.ts"), "utf8")).toBe(entry); + } finally { + await rm(root, { recursive: true, force: true }); + } + }); + + test("a hand-written declaration in another module still blocks removal", async () => { + const root = await mkdtemp(join(tmpdir(), "ctx-source-remove-declared-")); + try { + const initialized = await initContextProject({ cwd: root, projectDir: "kb", dev: true }); + const docs = join(root, "docs"); + await mkdir(docs, { recursive: true }); + await writeFile(join(docs, "guide.md"), "# Guide\n", "utf8"); + expect((await invokeCliInDir(initialized.projectRoot, [ + "source", "add", "file", "20260811", "--module", "guide", "--local", docs, "--format", "json", + ])).status).toBe(0); + await writeFile(join(initialized.projectRoot, "src/declared.ts"), [ + 'import { captureFile, defineProject, source } from "@c4a/context";', + 'const guide = source("20260811", "guide", { type: "file" });', + "export default defineProject({ sources: [guide], phases: [captureFile({ source: guide })], packages: [] });", + "", + ].join("\n"), "utf8"); + await writeFile(join(initialized.projectRoot, "src/index.ts"), 'export { default } from "./declared";\n', "utf8"); + const preview = await invokeCliInDir(initialized.projectRoot, ["source", "remove", "20260811/guide", "--format", "json"]); + expect(preview.stdout + preview.stderr).toContain("project.sources[0]"); + expect(await readFile(join(initialized.projectRoot, "sources/file/index.yaml"), "utf8")).toContain("guide"); + } finally { + await rm(root, { recursive: true, force: true }); + } + }); + test("removing an uncaptured Lark module preserves every snapshot in the shared batch directory", async () => { const root = await mkdtemp(join(tmpdir(), "ctx-source-remove-shared-lark-")); try { diff --git a/packages/context-cli/src/__tests__/versionRecordReviewGuard.test.ts b/packages/context-cli/src/__tests__/versionRecordReviewGuard.test.ts new file mode 100644 index 00000000..1499cdd7 --- /dev/null +++ b/packages/context-cli/src/__tests__/versionRecordReviewGuard.test.ts @@ -0,0 +1,34 @@ +import { afterEach, expect, test } from "bun:test"; +import { execFileSync } from "node:child_process"; +import { rm, writeFile } from "node:fs/promises"; +import { join, resolve } from "node:path"; +import { initialRevisionKnowledge } from "./initialRevisionKnowledge.fixture.js"; +import { completeApprovedRevision, prepareApprovedRevision, readApprovedRevision } from "../project/approvedRevision.js"; +import { readCandidateRecords } from "../project/candidateLedger.js"; + +const roots: string[] = []; +afterEach(async () => { for (const root of roots.splice(0)) await rm(root, { recursive: true, force: true }); }); +const cli = (root: string, args: string[]) => { + try { + return { ok: true, out: execFileSync("node", [resolve(import.meta.dir, "../../dist/cli.js"), ...args], + { cwd: root, encoding: "utf8", env: { ...process.env, CONTEXT_RUNTIME_EVENTS_DISABLED: "1" } }) }; + } catch (error) { + const output = error as { stdout?: string; stderr?: string }; + return { ok: false, out: `${output.stdout ?? ""}${output.stderr ?? ""}` }; + } +}; + +test("version record waits for drafts under review unless the workflow is at its record step", async () => { + const root = await initialRevisionKnowledge(roots); + await prepareApprovedRevision({ projectRoot: root, selector: "architecture/overview.md", instruction: "Clarify." }); + const request = (await readApprovedRevision(root))!; + await completeApprovedRevision({ projectRoot: root, revision: request.revision, + markdown: request.target.markdown.replace("value 42.", "value 42. Clarified.") }); + expect((await readCandidateRecords(root)).map(candidate => candidate.status)).toEqual(["draft"]); + const inspected = JSON.parse(cli(root, ["version", "inspect"]).out); + await writeFile(join(root, ".tmp/version.json"), JSON.stringify({ ...inspected.input_example, title: "Clarify", changes: ["Clarified"] })); + const refused = cli(root, ["version", "record", "--input", ".tmp/version.json", "--format", "json"]); + expect(refused.ok).toBe(false); + expect(refused.out).toContain("version-review-pending"); + expect(refused.out).toContain("Drafts are still awaiting review; the current step is review-current-batch"); +}, 60_000); diff --git a/packages/context-cli/src/cli.ts b/packages/context-cli/src/cli.ts index 755bd2db..56e4da45 100644 --- a/packages/context-cli/src/cli.ts +++ b/packages/context-cli/src/cli.ts @@ -457,6 +457,11 @@ const isDirectInvocation = isDirectCliInvocation(import.meta.url, process.argv[1]); if (isDirectInvocation) { + // A reader that stops early (`context status | head`) must not crash the + // command; it finishes its work and only the unread output is dropped. + for (const stream of [process.stdout, process.stderr]) { + stream.on("error", (error: NodeJS.ErrnoException) => { if (error.code !== "EPIPE") throw error; }); + } cli_main().catch((err: unknown) => { handleCliFailure(err); }); diff --git a/packages/context-cli/src/commands/actionCommands.ts b/packages/context-cli/src/commands/actionCommands.ts index 080174b9..79e35583 100644 --- a/packages/context-cli/src/commands/actionCommands.ts +++ b/packages/context-cli/src/commands/actionCommands.ts @@ -1,3 +1,4 @@ +import { withNextRoute } from "./nextRoute.js"; import { prepareApprovedRevisionSubmission } from "../project/approvedRevisionSubmission.js"; import { readApprovedRevision } from "../project/approvedRevision.js"; import { withSubmissionState } from "../project/submissionState.js"; @@ -60,8 +61,10 @@ export function registerProjectActionCommands(program: Command): void { ? await prepareApprovedRevisionSubmission({ projectRoot: root.projectRoot, revision, managed: options.managed === true, authorities: mergedWorkflowAuthorities(program.opts().workflowAuthority, []) }) : await prepareCurrentProductionStage({ projectRoot: root.projectRoot, revision, multiAgent: options.multiAgent === true, ...(options.source.length ? { sources: options.source } : {}) }); + // Stage preparation names the next step itself, so no separate status check is needed. + const output = "stage_state" in result || options.input ? await withNextRoute(program, root.projectRoot, result, { managed: options.managed === true }) : result; await new Promise((resolve, reject) => { - process.stdout.write(serializeActionCompletion(result, options.format as "json" | "yaml"), error => { + process.stdout.write(serializeActionCompletion(output, options.format as "json" | "yaml"), error => { if (error) reject(error); else resolve(); }); }); @@ -79,7 +82,7 @@ export function registerProjectActionCommands(program: Command): void { .argParser(collectWorkflowAuthorityOption) .default([]), ) - .option("--preview", "preview an approved revision, or every page of a prepared revision batch, without submitting; not used for production stage files") + .option("--preview", "check without submitting: an approved revision, every page of a prepared revision batch, or production stage article files") .option("--verbose", "include the full completion and next Route inline") .option("--format ", "output format: json | yaml", "json") .action(async (options: Record) => withSubmissionState(async () => { diff --git a/packages/context-cli/src/commands/documentRevisionCommands.ts b/packages/context-cli/src/commands/documentRevisionCommands.ts index 9ce87352..88b68ffa 100644 --- a/packages/context-cli/src/commands/documentRevisionCommands.ts +++ b/packages/context-cli/src/commands/documentRevisionCommands.ts @@ -1,4 +1,5 @@ import { Command } from "commander"; +import { withNextRoute } from "./nextRoute.js"; import { ErrorCategory } from "../lib/cliFeedback.js"; import { ContextError } from "../lib/errors.js"; import { beginDocumentRevision } from "../project/documentRevision.js"; @@ -16,20 +17,6 @@ function requireProjectRoot(): string { }); } -/** A committed result whose next step is only "check status" carries that status's Route, - * as `version record` does. If observing fails, the result keeps its status command. */ -async function withNextRoute(program: Command, projectRoot: string, result: unknown): Promise { - const next = (result as { next_action?: { command?: unknown } } | null)?.next_action?.command; - if (next !== "context status --format json") return result; - try { - const [{ collectProjectStatus }, { workflowAuthorities }] = await Promise.all([ - import("../project/status.js"), import("../project/workflow/workflowCommandOptions.js")]); - const root = program.opts() as { workflowManaged?: boolean; workflowAuthority?: unknown }; - const status = await collectProjectStatus(projectRoot, { managed: root.workflowManaged === true, authorities: workflowAuthorities(root.workflowAuthority) }); - return { ...(result as object), workflow: status.workflow }; - } catch { return result; } -} - export function registerDocumentRevisionCommand(program: Command): void { const task = program.command("task").description("Explicit current-task recovery"); task.command("retire").description("Preview or apply explicit approved-article retirement and reference cleanup") diff --git a/packages/context-cli/src/commands/nextRoute.ts b/packages/context-cli/src/commands/nextRoute.ts new file mode 100644 index 00000000..046b1e21 --- /dev/null +++ b/packages/context-cli/src/commands/nextRoute.ts @@ -0,0 +1,22 @@ +import type { Command } from "commander"; +import { mergedWorkflowAuthorities } from "../project/workflow/workflowCommandOptions.js"; + +/** The running command's own `--managed`/`--authority`, merged with the global options. */ +export function nextRouteExecution(program: Command, command: { managed?: boolean; authorities?: readonly string[] } = {}) { + const root = program.opts() as { workflowManaged?: boolean; workflowAuthority?: unknown }; + return { managed: root.workflowManaged === true || command.managed === true, + authorities: mergedWorkflowAuthorities(root.workflowAuthority, command.authorities ?? []) }; +} + +/** A result whose next step is only "check status", or that names none, carries that status's Route, + * as `version record` does. If observing fails, the result keeps its status command. */ +export async function withNextRoute(program: Command, projectRoot: string, result: unknown, + command: { managed?: boolean; authorities?: readonly string[] } = {}): Promise { + const next = (result as { next_action?: { command?: unknown } } | null)?.next_action; + if (next !== undefined && next.command !== "context status --format json") return result; + try { + const { collectProjectStatus } = await import("../project/status.js"); + const status = await collectProjectStatus(projectRoot, nextRouteExecution(program, command)); + return { ...(result as object), workflow: status.workflow }; + } catch { return result; } +} diff --git a/packages/context-cli/src/commands/versionCommands.ts b/packages/context-cli/src/commands/versionCommands.ts index 39bd90f8..09c2c172 100644 --- a/packages/context-cli/src/commands/versionCommands.ts +++ b/packages/context-cli/src/commands/versionCommands.ts @@ -1,4 +1,8 @@ import type { Command } from "commander"; +import { readCandidateRecords } from "../project/candidateLedger.js"; +import { ContextError } from "../lib/errors.js"; +import { ErrorCategory } from "../lib/cliFeedback.js"; +import { ExitCode } from "../types/exitCode.js"; import { findContextProjectRoot } from "../project/workspace.js"; import { readYamlOrJsonInput } from "../project/payloadInput.js"; import { changelogInputSchema, inspectWorkspaceVersion, recordWorkspaceVersion } from "../project/workspaceChangelog.js"; @@ -34,6 +38,19 @@ export function registerVersionCommands(program: Command) { ...(reference === undefined ? {} : { resourceReceiptsReference: reference }) }; const resourceReceipts = execution.resourceReceiptsReference === undefined ? undefined : await parseWorkflowResourceReceipts(execution.resourceReceiptsReference, root); + // Drafts still awaiting review: only the workflow's own record step may version them + // (partial delivery); otherwise review comes first. Rejected candidates do not count. + if ((await readCandidateRecords(root)).some(candidate => candidate.status === "draft")) { + const current = (await collectProjectStatus(root, { + ...execution, ...(resourceReceipts === undefined ? {} : { resourceReceipts }) })).workflow.current; + if (current?.node !== "record-workspace-version") { + throw new ContextError(ExitCode.WorkspaceStateError, `Drafts are still awaiting review; the current step is ${current?.node ?? "unknown"}, not version recording.`, { + category: ErrorCategory.WorkspaceStateInvalid, reason_code: "version-review-pending", + next_action: { command: current?.commands?.[0]?.command ?? workflowStatusCommand(execution) }, + next: "Finish the current step and Review first; the workflow reaches version recording after approval.", + }); + } + } const recorded = await recordWorkspaceVersion(root, value); // The transaction is committed before observing the next Route. A failed // observation must not invite the Agent to submit the version again. diff --git a/packages/context-cli/src/lib/gitProgress.ts b/packages/context-cli/src/lib/gitProgress.ts new file mode 100644 index 00000000..96645025 --- /dev/null +++ b/packages/context-cli/src/lib/gitProgress.ts @@ -0,0 +1,77 @@ +import { spawn } from "node:child_process"; + +/** Never echo credentials embedded in remote URLs. */ +export function redactRemoteCredentials(text: string): string { + return text.replace(/\/\/[^/@\s]+@/gu, "//"); +} + +export class GitProgressError extends Error { + constructor(message: string, readonly kind: "no-progress" | "too-long" | "failed") { super(message); } +} + +const UNITS: Record = { bytes: 1, KiB: 1024, MiB: 1024 ** 2, GiB: 1024 ** 3, TiB: 1024 ** 4 }; + +/** git's progress line, "Receiving objects: 40% (4/10), 1.20 MiB | 2.00 MiB/s" or + * "remote: Counting objects: 12": its phase, object count and bytes received so far. + * Other lines (warnings, retries) are not progress. */ +function progressCount(line: string): { phase: string; count: number; bytes: number } | undefined { + const match = /^(?:remote:\s*)?([A-Za-z][A-Za-z ]*?):\s+(?:\d+%\s+\((\d+)\/\d+\)|(\d+))/u.exec(line); + if (!match) return undefined; + const size = /,\s*(\d+(?:\.\d+)?)\s*(bytes|[KMGT]iB)(?!\/s)/u.exec(line.slice(match[0].length)); + return { phase: match[1]!, count: Number(match[2] ?? match[3]), bytes: size ? Number(size[1]) * UNITS[size[2]!]! : 0 }; +} + +/** Run a git fetch or clone while it makes progress. Progress means a phase's object count or + * received bytes in git's progress lines went up; repeated lines or warnings are not. Stops after + * `idleMs` without progress or `limitMs` in total, and reports which. Progress is shown on + * stderr only (throttled), never on stdout. */ +export async function runGitWithProgress(args: readonly string[], options: { + cwd?: string; env?: NodeJS.ProcessEnv; label: string; + idleMs?: number; limitMs?: number; reportMs?: number; bin?: string; +} ): Promise { + const idleMs = options.idleMs ?? 5 * 60_000, limitMs = options.limitMs ?? 30 * 60_000, reportMs = options.reportMs ?? 30_000; + const command = args.findIndex(arg => arg === "fetch" || arg === "clone"); + const argv = command < 0 ? [...args] : [...args.slice(0, command + 1), "--progress", ...args.slice(command + 1)]; + const child = spawn(options.bin ?? "git", argv, { cwd: options.cwd, env: options.env ?? process.env, stdio: ["ignore", "pipe", "pipe"] }); + const started = Date.now(); + let lastProgress = started, lastReport = started, lastLine = "", stdout = "", tail = ""; + const counts = new Map(); + child.stdout.on("data", chunk => { stdout += String(chunk); }); + child.stderr.on("data", chunk => { + const text = String(chunk); + tail = (tail + text).slice(-4000); + for (const line of text.split(/[\r\n]+/u).map(part => part.trim()).filter(Boolean)) { + const progress = progressCount(line); + if (!progress) continue; + lastLine = line; + const previous = counts.get(progress.phase); + if (!previous || progress.count > previous.count || progress.bytes > previous.bytes) { + counts.set(progress.phase, { count: Math.max(progress.count, previous?.count ?? 0), bytes: Math.max(progress.bytes, previous?.bytes ?? 0) }); + lastProgress = Date.now(); + } + } + }); + let stopped: GitProgressError | undefined; + const timer = setInterval(() => { + const now = Date.now(); + if (now - started > limitMs) stopped = new GitProgressError(`${options.label} stopped after ${Math.round(limitMs / 60_000)} minutes ` + + `(still running; last progress: ${redactRemoteCredentials(lastLine) || "none"}). Report this to the user before retrying.`, "too-long"); + else if (now - lastProgress > idleMs) stopped = new GitProgressError(`${options.label} made no progress for ${Math.round(idleMs / 60_000)} minutes ` + + `(last progress: ${redactRemoteCredentials(lastLine) || "none"}).`, "no-progress"); + if (stopped) { child.kill("SIGKILL"); return; } + if (now - lastReport >= reportMs && lastLine) { + lastReport = now; + process.stderr.write(`[context] ${options.label}: ${redactRemoteCredentials(lastLine)}\n`); + } + }, Math.min(1000, idleMs, limitMs)); + const code = await new Promise((resolve, reject) => { + child.once("error", reject); + child.once("close", resolve); + }).finally(() => clearInterval(timer)); + if (stopped) throw stopped; + if (code !== 0) { + const line = tail.split(/[\r\n]+/u).map(part => part.trim()).find(part => /^(fatal|error):/iu.test(part)) ?? tail.trim().split(/[\r\n]+/u).pop() ?? ""; + throw new GitProgressError(`${options.label} failed: ${redactRemoteCredentials(line).slice(0, 300) || `exit ${code}`}`, "failed"); + } + return stdout; +} diff --git a/packages/context-cli/src/lib/larkResourceCommand.ts b/packages/context-cli/src/lib/larkResourceCommand.ts index c7cceabb..e7ee4425 100644 --- a/packages/context-cli/src/lib/larkResourceCommand.ts +++ b/packages/context-cli/src/lib/larkResourceCommand.ts @@ -123,6 +123,18 @@ export async function runLarkResourceCommand( return result.stdout; } +/** Docs API code for an identity that cannot view the document (e.g. a synced block's source). */ +export const LARK_DOCUMENT_ACCESS_DENIED_CODE = "3380004"; + +/** What to do about a permission failure: an app scope is requested on the Lark Open Platform; + * document access is granted by the document's owner. */ +export function larkPermissionGuidance(error: unknown): string { + const stderr = error instanceof Error && "stderr" in error && typeof error.stderr === "string" ? error.stderr : ""; + const scope = (error instanceof LarkResourceCommandError && error.missingScope) || hasMissingScope(errorDetail(stderr)) || hasMissingScope(stderr); + return scope ? "Request the missing permission for the app at https://open.larkoffice.com/app, then capture again." + : "Ask the document's owner to share it with the capturing identity, then capture again."; +} + /** Only explicit permission failures qualify for non-blocking resource capture. */ export function isLarkResourcePermissionDenied(error: unknown): error is Error { if (!(error instanceof Error)) return false; @@ -134,6 +146,7 @@ export function isLarkResourcePermissionDenied(error: unknown): error is Error { return (error instanceof LarkResourceCommandError && error.missingScope) || hasMissingScope(detail) || hasMissingScope(stderr) || String(detail?.code) === "403" || + String(detail?.code) === LARK_DOCUMENT_ACCESS_DENIED_CODE || errorDetail(error.message)?.code === Number(LARK_DOCUMENT_ACCESS_DENIED_CODE) || (detail?.type === "authorization" && ["permission_denied", "access_denied", "missing_scope"].includes(String(detail.subtype ?? ""))); } diff --git a/packages/context-cli/src/lib/larkResourceMaterialization.ts b/packages/context-cli/src/lib/larkResourceMaterialization.ts index 67cffc13..f2099b62 100644 --- a/packages/context-cli/src/lib/larkResourceMaterialization.ts +++ b/packages/context-cli/src/lib/larkResourceMaterialization.ts @@ -14,6 +14,7 @@ import { import type { LarkExternalResource } from "./larkDocxXml.js"; import { isLarkResourcePermissionDenied, + larkPermissionGuidance, runLarkResourceCommand, type LarkResourceCommandRunner, } from "./larkResourceCommand.js"; @@ -727,7 +728,8 @@ export async function materializeLarkResources(input: MaterializeLarkResourcesIn required, asset_paths: [], ...(reasonCode === undefined ? {} : { reason_code: reasonCode }), - reason: error instanceof Error ? error.message : String(error), + // A permission gap says how to close it; the gap itself does not block the capture. + reason: `${error instanceof Error ? error.message : String(error)}${reasonCode === DOCUMENT_RESOURCE_PERMISSION_DENIED_REASON_CODE ? ` ${larkPermissionGuidance(error)}` : ""}`, }); } }; diff --git a/packages/context-cli/src/project/approvedRevisionReferences.ts b/packages/context-cli/src/project/approvedRevisionReferences.ts index 3af44cbe..e1907fd8 100644 --- a/packages/context-cli/src/project/approvedRevisionReferences.ts +++ b/packages/context-cli/src/project/approvedRevisionReferences.ts @@ -1,5 +1,5 @@ import { ZodError } from "zod"; -import { resolveSubmittedSourceLocator } from "./submittedSourceLocator.js"; +import { assertNoCaptureGap, resolveSubmittedSourceLocator } from "./submittedSourceLocator.js"; import { SubmissionInputError, SubmissionInputErrors } from "./productionFeedback.js"; import { articleFragmentReferences, createArticleSourceReference, repoContentScopeMatches, type ArticleSourceReference, type ArticleStructureEntry } from "@c4a/context"; @@ -48,7 +48,7 @@ async function resolveSubmittedReference(context: ReferenceContext, id: string, } const text = await context.readSource(reference.source_ref, reference.locator.path, true); let locator; - try { locator = resolveSubmittedSourceLocator(reference.locator, text); } + try { locator = resolveSubmittedSourceLocator(reference.locator, text); assertNoCaptureGap(locator, text); } catch (error) { if (error instanceof SubmissionInputError) throw new SubmissionInputError(`Fragment ${id}: ${error.message}`, [...at, "locator"]); throw error; diff --git a/packages/context-cli/src/project/articleReferenceObservation.ts b/packages/context-cli/src/project/articleReferenceObservation.ts index 1c7b1d4f..35c1b541 100644 --- a/packages/context-cli/src/project/articleReferenceObservation.ts +++ b/packages/context-cli/src/project/articleReferenceObservation.ts @@ -137,9 +137,10 @@ const exec = promisify(execFile); /** Display evidence only: every candidate is checked against the signed digest. * A bounded search may fail, which never changes the citation's classification. */ export function articleReferenceHistoryReader(root: string, previous: readonly ProcessedScope[] = []) { - const repoHistory = registeredRepoHistoryReader(root); + // Loaded on first use: a reader that is never asked must not leave a rejected promise behind. + let repoHistory: ReturnType | undefined; const objects = commandGitObjectReader(); - const registry = loadSourcesRegistry({ rootDir: root }); + let registry: ReturnType | undefined; const logs = new Map>(); function verified(reference: ArticleSourceReference, text: string, commit?: string): ReferenceHistory | undefined { try { @@ -153,7 +154,7 @@ export function articleReferenceHistoryReader(root: string, previous: readonly P if (reference.source_ref.startsWith("repo:")) { for (const scope of versions) { try { - const text = await (await repoHistory)(reference.source_ref, reference.locator.path, scope.processed_version); + const text = await (await (repoHistory ??= registeredRepoHistoryReader(root)))(reference.source_ref, reference.locator.path, scope.processed_version); const result = verified(reference, text, scope.processed_version); if (result) return result; } catch { /* Historical evidence is optional, unlike the current read. */ } @@ -161,7 +162,7 @@ export function articleReferenceHistoryReader(root: string, previous: readonly P return baseline === undefined ? undefined : { region: baseline }; } const [kind, name] = reference.source_ref.split(":", 2); - const sources = await registry; + const sources = await (registry ??= loadSourcesRegistry({ rootDir: root })); const entries = kind === "lark" ? sources.larks : kind === "file" ? sources.files : kind === "note" ? sources.notes : kind === "sessions" ? sources.sessions : []; const entry = entries.find(candidate => candidate.id === name || candidate.name === name); if (!entry) return baseline === undefined ? undefined : { region: baseline }; diff --git a/packages/context-cli/src/project/articleSourceReader.ts b/packages/context-cli/src/project/articleSourceReader.ts index 9b3fea9b..9a8d5e5a 100644 --- a/packages/context-cli/src/project/articleSourceReader.ts +++ b/packages/context-cli/src/project/articleSourceReader.ts @@ -1,3 +1,4 @@ +import { runGitWithProgress } from "../lib/gitProgress.js"; import { createHash } from "node:crypto"; import { execFile } from "node:child_process"; import { promisify } from "node:util"; @@ -20,15 +21,20 @@ function inside(root: string, path: string): void { /** Checkouts may be shallow or behind the registered commit. With `fetch`, a missing * commit is fetched once; otherwise reads stay local. A missing commit fails every * path at once instead of per read. */ -function commitAvailability(fetched: Map>, fetch = true) { +function commitAvailability(fetched: Map>, fetch = true, failures?: Map) { return (directory: string, commit: string) => { const key = `${directory}\0${commit}`; let result = fetched.get(key); if (!result) { + // A fetch runs while git reports progress; why it failed or stopped is kept for the caller. result = execute("git", ["-C", directory, "cat-file", "-e", `${commit}^{commit}`], { timeout: 5000, env: { ...process.env, GIT_NO_LAZY_FETCH: "1" } }).then(() => true, () => !fetch ? false : - execute("git", ["-C", directory, "fetch", "--quiet", "--depth=1", "origin", commit], { timeout: 120_000 }) - .then(() => true, () => false)); + runGitWithProgress(["-C", directory, "fetch", "--depth=1", "origin", commit], + { env: { ...process.env, GIT_TERMINAL_PROMPT: "0" }, label: `git fetch of commit ${commit.slice(0, 12)}` }) + .then(() => true, (error: unknown) => { + failures?.set(commit, error instanceof Error ? error.message : String(error)); + return false; + })); fetched.set(key, result); } return result; @@ -40,11 +46,13 @@ function missingCommit(commit: string): SourceUnavailableError { } /** Fetch commits the checkouts do not have yet (the registered one when omitted), one - * attempt each. Only `update --pending` calls this; every reader stays local. */ -export async function fetchSourceCommits(projectRoot: string, requests: ReadonlyArray<{ source_ref: string; commit?: string }>): Promise { + * attempt each. Only `update --pending` calls this; every reader stays local. Returns the + * reason for each commit whose fetch failed or was stopped. */ +export async function fetchSourceCommits(projectRoot: string, requests: ReadonlyArray<{ source_ref: string; commit?: string }>): Promise> { const workspace = await realpath(projectRoot); const registry = await loadSourcesRegistry({ rootDir: projectRoot }); - const available = commitAvailability(new Map(), true); + const failed = new Map(); + const available = commitAvailability(new Map(), true, failed); for (const request of requests) { if (!request.source_ref.startsWith("repo:")) continue; const name = request.source_ref.slice("repo:".length); @@ -54,6 +62,7 @@ export async function fetchSourceCommits(projectRoot: string, requests: Readonly const root = await realpath(resolve(workspace, entry.materializedAt)).catch(() => undefined); if (root) await available(root, commit); } + return failed; } /** Reads a registered repository file at an earlier commit; callers must verify @@ -168,7 +177,11 @@ export async function registeredArticleSourceReader(projectRoot: string) { pending = (async () => { try { const { root, files, commit } = await scope(sourceRef); - if (files && !files.has(path)) throw new SourceUnavailableError("Source path is not owned by the registered document", "source-path-unregistered"); + if (files && !files.has(path)) { + const owned = [...files.keys()]; + throw new SourceUnavailableError(`Source path ${path} is not owned by the registered document ${sourceRef}; cite one of its files: ` + + `${owned.slice(0, 10).join(", ")}${owned.length > 10 ? `, and ${owned.length - 10} more` : ""}.`, "source-path-unregistered"); + } const lexical = resolve(root, path); inside(root, lexical); let bytes: Uint8Array; diff --git a/packages/context-cli/src/project/documentCaptureLark.ts b/packages/context-cli/src/project/documentCaptureLark.ts index e7b27e6d..b3d49e49 100644 --- a/packages/context-cli/src/project/documentCaptureLark.ts +++ b/packages/context-cli/src/project/documentCaptureLark.ts @@ -4,6 +4,7 @@ import { readdir, readFile } from "node:fs/promises"; import { basename, extname, join } from "node:path"; import type { CaptureLarkPhaseDefinition, LarkSourceRegistryEntry } from "@c4a/context"; import { + isNonBlockingDocumentResourceFailureReasonCode, computeDocumentContentHash, createDocumentSnapshotManifest, normalizeMarkdownDocument, @@ -449,13 +450,17 @@ async function runCaptureLarkPhaseUnlocked(input: { // A retry must not replace previously captured resources with transient // failures. Keep the complete old snapshot; do not claim stale bytes are fresh. + // A located gap (permission, source missing) or a preview is saved and listed instead. + let degraded: typeof fetched.resourceMaterialization.items = []; if (previousManifest && previousRevision !== undefined && fetched.revisionId === previousRevision) { const previous = documentSnapshotFidelityState(previousManifest, readDocumentSnapshotCaptureReport({ projectRoot: input.projectRoot, materializedAt, manifest: previousManifest, })); - const lost = fetched.resourceMaterialization.items.filter(item => + let lost = fetched.resourceMaterialization.items.filter(item => previous.resourceMaterialization?.items.some(old => old.kind === item.kind && old.locator === item.locator && old.status === "materialized" && (item.status !== "materialized" || item.reason_code === "document.resource.preview" && old.reason_code !== "document.resource.preview"))); + degraded = lost.filter(item => item.status === "materialized" || isNonBlockingDocumentResourceFailureReasonCode(item.reason_code)); + lost = lost.filter(item => !degraded.includes(item)); if (lost.length) throw new ContextError(ExitCode.WorkspaceStateError, "Previously captured resources were degraded; the existing snapshot was preserved. Check resource policy and access before retrying the explicit refresh.", { category: ErrorCategory.PartialFailure, reason_code: DOCUMENT_ACQUISITION_UNAVAILABLE, @@ -661,6 +666,10 @@ async function runCaptureLarkPhaseUnlocked(input: { ...fetched.resourceMaterialization.items .filter((item) => item.status === "failed" || (item.kind === "poll" && item.reason?.includes("absent") === true)) .map((item) => `${item.status}: lark.capture.resource-${item.status}: ${item.kind}: ${item.reason ?? item.locator}`), + ...fetched.resourceMaterialization.items.filter(item => item.reason_code === "document.resource.preview") + .map(item => `warning: lark.capture.resource-preview: ${item.kind}: ${item.reason ?? item.locator}`), + ...degraded.map(item => `warning: lark.capture.resource-degraded: ${item.kind} ${item.locator} was captured before and is now ` + + `${item.status === "materialized" ? "a preview" : "a gap"}; its placeholder is not citable evidence`), ], next_action: workspaceRouteReevaluation(input.phase.id), }; diff --git a/packages/context-cli/src/project/knowledgeUpdate.ts b/packages/context-cli/src/project/knowledgeUpdate.ts index ce7da48c..35151e26 100644 --- a/packages/context-cli/src/project/knowledgeUpdate.ts +++ b/packages/context-cli/src/project/knowledgeUpdate.ts @@ -73,11 +73,14 @@ export async function readKnowledgeUpdate(projectRoot: string): Promise>["unresolved"], - prepared: readonly RepositoryContentPreparation[], network: boolean): void { + prepared: readonly RepositoryContentPreparation[], network: boolean, + fetchFailures: ReadonlyMap = new Map(), registered: ReadonlyMap = new Map()): void { const missingCommits = [...new Set(unresolved.filter(item => item.reason === "source-history-missing") .map(item => item.reference.source_ref))]; if (missingCommits.length) { - throw new TypeError(`The registered commit of ${missingCommits.join(", ")} is not in its source checkout${network ? " and could not be fetched" : ""}. ` + + const why = missingCommits.map(source => fetchFailures.get(registered.get(source) ?? "")).filter(Boolean); + throw new TypeError(`The registered commit of ${missingCommits.join(", ")} is not in its source checkout${network ? " and could not be fetched" : ""}` + + `${why.length ? ` (${why.join("; ")})` : ""}. ` + "Check that the registered commit SHA exists in the remote repository. " + (network ? "If it does, fetch and check out the registered commit in the source checkout (see context source list --format json), then rerun context update --pending --format json." : "context update --pending fetches it; an explicit update reads only what the checkout has, so fetch and check out the commit first, then rerun this update.")); @@ -148,13 +151,15 @@ export async function beginKnowledgeUpdate(projectRoot: string, value: unknown, // partial clone lacks. An explicit update reads what the checkouts already have. const network = options.pending === true; let prepared: Awaited> = []; + let fetchFailures = new Map(); if (network) { - await fetchSourceCommits(projectRoot, [...repoScopes.map(source_ref => ({ source_ref })), + fetchFailures = await fetchSourceCommits(projectRoot, [...repoScopes.map(source_ref => ({ source_ref })), ...comparisons.map(item => ({ source_ref: item.source_ref, commit: item.from }))]); prepared = await prepareRepositoryContents(projectRoot, repoScopes.map(source => ({ source_ref: source, paths: citedPaths(source, cited) }))); } const inspected = await inspectSettledReferences(projectRoot, cited, scopes.map(scope => scope.source_ref), settled); - stopOnUnreadableSources(inspected.unresolved, prepared, network); + stopOnUnreadableSources(inspected.unresolved, prepared, network, fetchFailures, + new Map(scopes.map(scope => [scope.source_ref, scope.processed_version]))); // History is optional evidence: prepare old contents only for citations that need it, // and continue without it when it cannot be downloaded. if (network) await prepareRepositoryContents(projectRoot, repoScopes.flatMap(source => { diff --git a/packages/context-cli/src/project/productionAction.ts b/packages/context-cli/src/project/productionAction.ts index b251ce5d..e0717f68 100644 --- a/packages/context-cli/src/project/productionAction.ts +++ b/packages/context-cli/src/project/productionAction.ts @@ -26,7 +26,6 @@ export async function completeCurrentProductionAction(input: { next_action: { command: "context status --format json" }, }); if (!stage) throw invalid("The production stage expired. Read the current route; do not restore a previous process."); - if (input.preview) throw invalid("Stage files do not use the retired Author preview. Submit the current task files."); if (!input.submissionPath || input.submissionPath === "-") throw invalid("Production requires a stage-local manifest file, not stdin."); const path = relative(resolve(input.projectRoot, productionAgentDirectory(stage.id)), resolve(input.cwd, input.submissionPath)); const manifest = await readProductionFile({ projectRoot: input.projectRoot, stage: stage.id, path }); @@ -35,9 +34,15 @@ export async function completeCurrentProductionAction(input: { throw invalid("The manifest must identify the current production stage. No tasks were saved."); } const submission = { projectRoot: input.projectRoot, stage: stage.id, path, manifest, multiAgent: input.multiAgent === true }; - if ("decision" in value) return approveProductionReport({ ...submission, revision: input.revision }); + if ("decision" in value) { + if (input.preview) throw invalid("--preview checks article task files; a report decision has nothing to preview."); + return approveProductionReport({ ...submission, revision: input.revision }); + } if (input.revision !== stage.id) throw invalid("Use the current stage revision; task input handles protect independent submissions."); - if (!stage.planning_complete || "articles" in value) return submitProductionPlan(submission); - return completeProductionSubmission(submission); + if (!stage.planning_complete || "articles" in value) { + if (input.preview) throw invalid("--preview checks article task files; submit the plan to have it checked."); + return submitProductionPlan(submission); + } + return completeProductionSubmission({ ...submission, preview: input.preview === true }); })); } diff --git a/packages/context-cli/src/project/productionArticle.ts b/packages/context-cli/src/project/productionArticle.ts index 57d17243..70d99ba1 100644 --- a/packages/context-cli/src/project/productionArticle.ts +++ b/packages/context-cli/src/project/productionArticle.ts @@ -1,7 +1,8 @@ -import { resolveSubmittedSourceLocator } from "./submittedSourceLocator.js"; +import { assertNoCaptureGap, resolveSubmittedSourceLocator } from "./submittedSourceLocator.js"; import YAML from "yaml"; import { z, ZodError } from "zod"; import { ARTICLE_FRAGMENT_REGION_LIMIT, ARTICLE_FRAGMENT_SOURCE_FILE_LIMIT, articleFragmentReferences, createArticleSourceReference, + type ArticleSourceReference, indexerKnowledgeCollectionSchema, indexerProtocolDigest, repoContentScopeMatches } from "@c4a/context"; import { ContextError } from "../lib/errors.js"; import { ErrorCategory } from "../lib/cliFeedback.js"; @@ -10,6 +11,9 @@ import { approvedContextSectionsInMarkdown } from "./verifyContextSections.js"; import { indexerCandidateId, isReservedKnowledgeIndexPath, isSafeKnowledgeTargetPath, parseCandidateRecord, type CandidateRecord } from "./candidateLedger.js"; import { registeredArticleSourceReader } from "./articleSourceReader.js"; +import { createArticleReferenceObserver, type SourceRead } from "./articleReferenceObservation.js"; +import { suggestedCitation } from "./approvedRevisionReferences.js"; +import { SourceUnavailableError } from "./gitObjectReader.js"; import { rememberArticleRegion } from "./articleRegionBaselines.js"; import { applyProductionArticleEdits, productionReferenceInputSchema, type ProductionArticleBase } from "./productionArticleEdits.js"; import type { ProductionTask } from "./productionStage.js"; @@ -23,7 +27,7 @@ export const productionReferencesSchema = z.object({ }).strict()), }).strict(); -export type ProductionSourceReader = (source: string, path: string, captured?: boolean) => Promise; +export type ProductionSourceReader = SourceRead; /** Warm this submission's existing reader, not a persistent evidence cache. * Only declared, authorized references are read; normal compilation remains @@ -64,6 +68,32 @@ function articleError(task: ProductionTask, file: string, message: string, secti }); } +/** The earlier citation a submitted reference repeats (same source, file and lines). */ +function earlierCitation(base: ProductionArticleBase | undefined, + retained: ReturnType["retainedReferences"] | undefined, fragment: string, + ref: { source_ref: string; locator: Record }): ArticleSourceReference | undefined { + if (!("start_line" in ref.locator)) return undefined; + const signed = (value: { source_ref: string; locator: Record; content_digest?: string }): value is ArticleSourceReference => + !!value.content_digest && "start_line" in value.locator; + const same = (value: ArticleSourceReference) => value.source_ref === ref.source_ref && value.locator.path === ref.locator.path && + value.locator.start_line === ref.locator.start_line && value.locator.end_line === ref.locator.end_line; + const from = (references: ReadonlyArray<{ source_ref: string; locator: Record; content_digest?: string }> | undefined) => + references?.filter(signed).find(same); + return from(base?.sections.find(section => section.id === fragment)?.references) ?? from(retained?.get(fragment)); +} + +/** Signed citations of a base, for location suggestions. */ +const signedSections = (base: ProductionArticleBase | undefined) => (base?.sections ?? []).map(section => ({ id: section.id, + references: section.references.filter((value): value is ArticleSourceReference => !!value.content_digest && "start_line" in value.locator) })); + +function outsideSourceMessage(task: ProductionTask, source: string, authorization?: { requirements: string[]; dependents: string[] }): string { + const owners = authorization?.requirements.length ? `requirement ${authorization.requirements.join(", ")}` : "the requirement that owns this article"; + const replaced = [task.id, ...authorization?.dependents ?? []]; + return `Source is outside this task's authorized inputs: ${source}. Cite only ${task.sources.map(item => item.scope).join(", ")}, ` + + `or authorize it: add ${source} to evidence_source_scope of ${owners} in src/indexers.yaml, then submit a plan amendment ` + + `whose replaces lists ${replaced.join(", ")}${replaced.length > 1 ? " (this task and the tasks that depend on it)" : ""} with a new task that includes the source.`; +} + /** Compile one fixed complete article into the existing Candidate model. Source * references are computed from authorized text, never accepted as Agent hashes. * This function does not persist, approve, publish or load Provider metadata. */ @@ -77,6 +107,10 @@ export async function prepareProductionArticle(input: { /** Validated candidate/approved references only; repair drafts never grant authority. */ trustedBase?: ProductionArticleBase; approvedBaseDigest: string | null; + /** Checks only: no source-region cache writes. */ + preview?: boolean; + /** How to authorize another source: owning requirements and the tasks an amendment must replace. */ + authorization?: () => Promise<{ requirements: string[]; dependents: string[] }>; }): Promise { const { task } = input; let files = input.files; @@ -138,36 +172,62 @@ export async function prepareProductionArticle(input: { if (oversized.length) throw articleError(task, files.references.path, `Split the claims or choose sufficient references for these fragments: ${oversized.join("; ")}.`); const read = input.sourceReader ?? await registeredArticleSourceReader(input.projectRoot); + const observe = createArticleReferenceObserver(read); const allowed = new Set(task.sources.map(source => source.scope)); + // Every reference problem of the article is reported together, one entry per fragment problem. + const problems: Array<{ section: string; message: string }> = []; const sections = []; for (const fragment of fragments) { const references = []; for (const ref of byId.get(fragment.id)!) { try { + // Repeating an earlier citation's lines keeps that evidence: it follows text that only + // moved (one unique match) and is reported otherwise, never re-signed at the old lines. + const earlier = earlierCitation(input.trustedBase ?? input.base, retained, fragment.id, ref); + // Only a citation the edit retains from the validated base keeps its earlier authority. const inherited = retained?.get(fragment.id)?.some(value => value.source_ref === ref.source_ref && indexerProtocolDigest(value.locator) === indexerProtocolDigest(ref.locator)); - const trusted = inherited ? input.trustedBase?.sections.find(section => section.id === fragment.id)?.references.find(value => - value.source_ref === ref.source_ref && indexerProtocolDigest(value.locator) === indexerProtocolDigest(ref.locator)) : undefined; - if (!trusted?.content_digest && ![...allowed].some(scope => repoContentScopeMatches(scope, ref.source_ref))) throw new TypeError(`Source is outside this task's authorized inputs: ${ref.source_ref}`); - const text = await read(ref.source_ref, ref.locator.path, true); - const reference = createArticleSourceReference(ref.source_ref, resolveSubmittedSourceLocator(ref.locator, text), text); - const previous = trusted ?? retained?.get(fragment.id)?.find(value => value.source_ref === ref.source_ref && - indexerProtocolDigest(value.locator) === indexerProtocolDigest(ref.locator)); - if (previous?.content_digest && previous.content_digest !== reference.content_digest) { - throw new TypeError("Retained source text changed. Read it and explicitly revise this fragment's references; a body-only edit cannot confirm changed evidence."); + const trusted = inherited && earlier && input.trustedBase?.sections.find(section => section.id === fragment.id)?.references + .some(value => value.content_digest === earlier.content_digest); + if (!trusted && ![...allowed].some(scope => repoContentScopeMatches(scope, ref.source_ref))) throw new TypeError(outsideSourceMessage(task, ref.source_ref, await input.authorization?.())); + if (earlier) { + const observed = await observe(earlier); + if (observed.state === "current" || observed.state === "moved") { references.push(observed.reference); continue; } + const hint = observed.state === "not-found" + ? await suggestedCitation(input.projectRoot, earlier, signedSections(input.trustedBase)).catch(() => undefined) : undefined; + throw new TypeError(`${earlier.source_ref} ${earlier.locator.path}:${earlier.locator.start_line}-${earlier.locator.end_line} repeats an earlier citation, ` + + `which is ${observed.state}${observed.reason ? ` (${observed.reason})` : ""} in the current source. ` + + `Rewrite the fragment, cite its current text${hint ? ` (${hint})` : ""} with a quote or new lines, or remove the citation.`); } - rememberArticleRegion(input.projectRoot, reference, text); + const text = await read(ref.source_ref, ref.locator.path, true); + const locator = resolveSubmittedSourceLocator(ref.locator, text); + assertNoCaptureGap(locator, text); + const reference = createArticleSourceReference(ref.source_ref, locator, text); + if (!input.preview) rememberArticleRegion(input.projectRoot, reference, text); references.push(reference); } catch (error) { - throw articleError(task, files.references.path, error instanceof Error ? error.message : String(error), fragment.id); + if (error instanceof ContextError && error.detail?.reason_code !== "source-read-failed" && !(error instanceof SourceUnavailableError)) throw error; + const message = error instanceof Error ? error.message : String(error); + // Name the citation when the message itself does not (a range beyond the file's end). + problems.push({ section: fragment.id, message: error instanceof RangeError && "start_line" in ref.locator + ? `${ref.source_ref} ${ref.locator.path}:${ref.locator.start_line}-${ref.locator.end_line}: ${message}` : message }); } } let unique; try { unique = articleFragmentReferences(references); } - catch (error) { throw articleError(task, files.references.path, error instanceof ZodError ? error.issues.map(issue => issue.message).join("; ") : error instanceof Error ? error.message : String(error), fragment.id); } + catch (error) { + problems.push({ section: fragment.id, message: error instanceof ZodError ? error.issues.map(issue => issue.message).join("; ") : error instanceof Error ? error.message : String(error) }); + continue; + } sections.push({ section_ref: `${task.article_id}#${fragment.id}`, section_key: fragment.id, references: unique, markdown: fragment.readerVisibleBody, markdown_digest: indexerProtocolDigest(fragment.readerVisibleBody) }); } + if (problems.length) { + const error = articleError(task, files.references.path, problems.length === 1 ? problems[0]!.message + : `${problems.length} reference problems: ${problems.map((item, index) => `(${index + 1}) ${item.section}: ${item.message}`).join(" ")}`, problems[0]!.section); + (error.detail as Record).problems = problems; + throw error; + } const fingerprint = indexerProtocolDigest({ input: task.input, markdown, sections }); return parseCandidateRecord({ candidate_id: indexerCandidateId(fingerprint), article_id: task.article_id, collection, diff --git a/packages/context-cli/src/project/productionKnownTasks.ts b/packages/context-cli/src/project/productionKnownTasks.ts index 9ee93ee3..cd756ccf 100644 --- a/packages/context-cli/src/project/productionKnownTasks.ts +++ b/packages/context-cli/src/project/productionKnownTasks.ts @@ -37,16 +37,27 @@ export async function prepareKnownProductionTasks(input: { if (!request || stage?.report_approved || (stage ? ![stage.id, request.revision].includes(input.revision) : request.revision !== input.revision)) { throw invalid("Use known tasks before report approval, with the current preparation revision. Approved stages use ordinary task amendments."); } - if (!stage) { - await prepareCurrentProductionStage({ projectRoot: input.projectRoot, revision: input.revision, + // A stage whose sources could not be read last time is checked again, not reused as failed. + if (!stage || stage.gaps.length) { + await prepareCurrentProductionStage({ projectRoot: input.projectRoot, revision: stage?.id ?? input.revision, sources: [...new Set([...plan.articles.flatMap(article => article.sources), ...plan.pending_scopes ?? []])] }); stage = (await readProductionStage(input.projectRoot))!; } // Validate and accept exactly the fixed input already read. Neither this // step nor submission reopens the Agent file after preparation. const text = YAML.stringify({ ...plan, stage: stage.id }); - const result = await submitProductionPlan({ projectRoot: input.projectRoot, stage: stage.id, path: fixed.path, - manifest: { path: fixed.path, text, bytes: Buffer.byteLength(text), digest: durableContentDigest(text) } }); + let result; + try { + result = await submitProductionPlan({ projectRoot: input.projectRoot, stage: stage.id, path: fixed.path, + manifest: { path: fixed.path, text, bytes: Buffer.byteLength(text), digest: durableContentDigest(text) } }); + } catch (error) { + // Rerunning this same command re-checks the sources, so it is the next step. + if (error instanceof ContextError && error.detail?.reason_code === "production-planning-refresh-required") { + error.detail.next_action = { command: `context action prepare-current --revision ${stage.id} --input ${input.path} --format json`, + instruction: "Restore or check the listed sources if needed, then rerun this command; it checks them again and submits the same tasks." }; + } + throw error; + } return { ...result, next_action: { command: "context status --format json" } }; })); } diff --git a/packages/context-cli/src/project/productionPlanningMaterials.ts b/packages/context-cli/src/project/productionPlanningMaterials.ts index e557c378..d362e1df 100644 --- a/packages/context-cli/src/project/productionPlanningMaterials.ts +++ b/packages/context-cli/src/project/productionPlanningMaterials.ts @@ -19,6 +19,29 @@ const markdownParser = unified().use(remarkParse); type MarkdownRoot = ReturnType; type MarkdownNode = MarkdownRoot | MarkdownRoot["children"][number]; +/** Whether a repository checkout matches its registered commit. Only `git diff` exit 1 means it + * differs; a slow first index refresh or a lock held by another git command is retried once and + * then reported as unchecked, never as a missing source. The check writes no index (no locks). */ +export async function checkoutMatchesCommit(root: string, ref: string, files: number): + Promise<{ state: "same" | "differs" } | { state: "unchecked"; reason: string }> { + // Large checkouts on slow disks need a cold index refresh: scale with the file count. + const timeout = 30_000 + files * 2; + let reason = ""; + for (let attempt = 0; attempt < 2; attempt++) { + try { + await execute("git", ["-C", root, "diff", "--quiet", ref, "--", "."], { timeout, maxBuffer: 64 * 1024, + env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" } }); + return { state: "same" }; + } catch (error) { + const failure = error as { code?: unknown; killed?: boolean; stderr?: string }; + if (failure.code === 1) return { state: "differs" }; + reason = failure.killed ? `timed out after ${Math.round(timeout / 1000)} s` + : String(failure.stderr ?? (error instanceof Error ? error.message : error)).trim().split("\n")[0]!.slice(0, 200); + } + } + return { state: "unchecked", reason }; +} + /** Cheap document navigation. The CLI scans text to extract headings; the * Agent receives a bounded opening plus the complete H2/H3 outline, not every * document body and not an invented semantic partition. */ @@ -114,16 +137,16 @@ export async function prepareProductionPlanningMaterials(input: { if (type === "repo") { const repo = registry.repos.find(repo => repo.id === name || repo.name === name)!; if (!/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/u.test(repo.ref)) throw new TypeError("Planning requires a captured fixed commit, not a moving ref"); - await execute("git", ["-C", root, "diff", "--quiet", repo.ref, "--", "."], { - timeout: 5000, maxBuffer: 64 * 1024, - }); const targets = input.requirements.requirements.flatMap(item => [...item.target_scope.targets, ...item.evidence_source_scope?.targets ?? []]).filter(target => target.source_ref === scope); const modules = [...new Set(targets.flatMap(target => target.module_refs ?? []))]; const result = await execute("git", ["-C", root, "ls-tree", "-r", "--name-only", "-z", repo.ref], { - encoding: "utf8", timeout: 5000, maxBuffer: 8 * 1024 * 1024, + encoding: "utf8", timeout: 60_000, maxBuffer: 64 * 1024 * 1024, }); - const files = result.stdout.split("\0").filter(path => path && !sourceExcludes(input.requirements, scope, path)); + const tracked = result.stdout.split("\0").filter(Boolean); + const checkout = await checkoutMatchesCommit(root, repo.ref, tracked.length); + if (checkout.state === "differs") throw new TypeError(`The checkout differs from the registered commit ${repo.ref}; restore it (context source recovery-plan --format json) before planning`); + const files = tracked.filter(path => !sourceExcludes(input.requirements, scope, path)); const directories = new Map(); for (const file of files) { const directory = file.includes("/") ? file.split("/")[0]! : "(root)"; @@ -132,7 +155,9 @@ export async function prepareProductionPlanningMaterials(input: { sources.set(scope, [`# ${scope}`, "", `Authorized repository boundary: ${root}`, `Captured commit: ${repo.ref}`, ...(modules.length ? [`Module focus: ${modules.join(", ")}`] : []), "Choose relevant directories while investigating. Module names are work guidance, not inferred path permissions; put useful reading scope in the task brief without a separate mapping or receipt.", - `Complete authorized tracked-file count: ${files.length}`, "", "## Directory skeleton", "", + `Complete authorized tracked-file count: ${files.length}`, + ...(checkout.state === "unchecked" ? [`Checkout check did not complete (${checkout.reason}); the skeleton is read from the registered commit. Read source files through the commit, not the working tree.`] : []), + "", "## Directory skeleton", "", ...[...directories].sort(([a], [b]) => a.localeCompare(b)).map(([directory, count]) => `- ${directory}: ${count} files`), "", "## File navigation sample", "", ...files.slice(0, 128).map(path => `- ${path}`), ...(files.length > 128 ? [`${files.length - 128} additional filenames are omitted here; investigate the relevant directory within the authorized boundary.`] : []), diff --git a/packages/context-cli/src/project/productionSubmission.ts b/packages/context-cli/src/project/productionSubmission.ts index 4f0ecc19..5088b128 100644 --- a/packages/context-cli/src/project/productionSubmission.ts +++ b/packages/context-cli/src/project/productionSubmission.ts @@ -43,6 +43,12 @@ function writeTarget(path: string, previous: string | undefined, content: string target_digest: durableContentDigest(content), content }; } +/** A check of stage task files with the submission rules; nothing is saved. */ +export interface ProductionSubmissionPreview { + protocol: "context.production-submission-preview/v1"; written: false; + ok: string[]; failed: ProductionSubmissionResult["failed"]; +} + export interface ProductionSubmissionResult { submission_state: "committed" | "not-committed"; accepted: Array<{ task: string; receipt: string }>; @@ -56,14 +62,22 @@ export interface ProductionSubmissionResult { * the successful subset. Neither * candidates nor deduplication records escape .tmp. A new machine starts fresh. * The caller may materialize newly eligible work without a full status query. */ -export async function completeProductionSubmission(input: { +type ProductionSubmissionInput = Parameters[0]; +export function completeProductionSubmission(input: ProductionSubmissionInput & { preview: true }): Promise; +export function completeProductionSubmission(input: ProductionSubmissionInput & { preview?: false }): Promise; +export function completeProductionSubmission(input: ProductionSubmissionInput): Promise; +export function completeProductionSubmission(input: ProductionSubmissionInput) { return completeProductionSubmissionImpl(input); } + +async function completeProductionSubmissionImpl(input: { projectRoot: string; stage: string; path: string; manifest?: FixedProductionFile; multiAgent?: boolean; prepareNext?: (stage: ProductionStage) => Promise> | void>; -}): Promise { + /** Check every task with the submission rules, then return without saving anything. */ + preview?: boolean; +}): Promise { return withProjectWriteLock(input.projectRoot, "production-submit", async () => { await recoverDurableMultiFileTransactions(input.projectRoot); const snapshot = await readProductionStageSnapshot(input.projectRoot); @@ -154,14 +168,15 @@ export async function completeProductionSubmission(input: { // when a prior formal/candidate version also exists. base = await readProductionRepairDraft({ projectRoot: input.projectRoot, stage: stage.id, task }) ?? base; } - retainDraft = !!files.content && !!files.references; + retainDraft = !input.preview && !!files.content && !!files.references; const candidate = await measureContextDebugOperation({ projectRoot: input.projectRoot, operation: "production.submit.validate" }, () => prepareProductionArticle({ projectRoot: input.projectRoot, task, files, sourceReader: sourceReader!, approvedBaseDigest: target.approvedBaseDigest, ...(base ? { base } : {}), ...(target.base ? { trustedBase: target.base } : {}), - visibility: target.visibility })); + visibility: target.visibility, preview: input.preview === true, + authorization: () => productionAuthorization(input.projectRoot, stage!, task) })); // Make successful proposals visible to subsequent conflict checks, // without exposing any acceptance until their joint transaction saves. const key = knowledgeTargetPathKey(candidate.path); @@ -171,16 +186,28 @@ export async function completeProductionSubmission(input: { } catch (error) { const detail = error && typeof error === "object" && "detail" in error ? error.detail as Record | undefined : undefined; - let reason = error instanceof Error ? error.message : String(error); + const reason = error instanceof Error ? error.message : String(error); + let note = ""; if (retainDraft) { try { await retainProductionRepairDraft({ projectRoot: input.projectRoot, stage: stage.id, task, files }); } - catch { reason += " The temporary repair draft could not be retained; resubmit the complete draft."; } + catch { note = " The temporary repair draft could not be retained; resubmit the complete draft."; } + } + // An article with several reference problems reports each fragment's problem. + const problems = Array.isArray(detail?.problems) ? detail.problems as Array<{ section: string; message: string }> + : [{ section: detail?.section, message: reason }]; + for (const item of problems) { + result.failed.push({ task: task.id, reason: item.message + note, + ...(typeof detail?.file === "string" ? { file: detail.file } : {}), + ...(typeof item.section === "string" ? { section: item.section } : {}) }); } - result.failed.push({ task: task.id, reason, - ...(typeof detail?.file === "string" ? { file: detail.file } : {}), - ...(typeof detail?.section === "string" ? { section: detail.section } : {}) }); } } + if (input.preview) { + const order = new Map(fixed.tasks.map((task, index) => [task.task, index])); + return { protocol: "context.production-submission-preview/v1", written: false, + ok: [...result.accepted.map(item => item.task), ...pending.keys()].sort((a, b) => order.get(a)! - order.get(b)!), + failed: result.failed }; + } if (pending.size) { const changedArticles = new Set([...pending.values()].map(proposal => proposal.candidate.article_id)); const nextCandidates = [...candidates.filter(candidate => !changedArticles.has(candidate.article_id)), @@ -231,3 +258,21 @@ export async function completeProductionSubmission(input: { return result; }); } + +/** Owning requirements and the active tasks (transitively) waiting on this one. */ +async function productionAuthorization(projectRoot: string, stage: ProductionStage, task: ProductionStage["tasks"][number]) { + const { readProductionRequirements } = await import("./productionRequirements.js"); + const sources = new Set(task.sources.map(source => source.scope)); + const requirements = await readProductionRequirements(projectRoot).then(value => value.requirements + .filter(item => [...item.target_scope.targets, ...item.evidence_source_scope?.targets ?? []].some(target => sources.has(target.source_ref))) + .map(item => item.id), () => []); + const dependents: string[] = []; + for (let added = true; added;) { + added = false; + for (const other of stage.tasks) { + if (dependents.includes(other.id) || ["accepted", "excluded", "replaced"].includes(other.status)) continue; + if (other.after.some(id => id === task.id || dependents.includes(id))) { dependents.push(other.id); added = true; } + } + } + return { requirements, dependents }; +} diff --git a/packages/context-cli/src/project/repoContentPrefetch.ts b/packages/context-cli/src/project/repoContentPrefetch.ts index d2acf352..d23a71e6 100644 --- a/packages/context-cli/src/project/repoContentPrefetch.ts +++ b/packages/context-cli/src/project/repoContentPrefetch.ts @@ -3,6 +3,7 @@ import { realpath } from "node:fs/promises"; import { resolve } from "node:path"; import { promisify } from "node:util"; import { loadSourcesRegistry } from "@c4a/context"; +import { redactRemoteCredentials, runGitWithProgress } from "../lib/gitProgress.js"; const execute = promisify(execFile); const offline = { ...process.env, GIT_NO_LAZY_FETCH: "1" }; @@ -60,12 +61,6 @@ async function missingObjects(root: string, commit: string, paths: readonly stri return checked.split("\n").filter(line => line.endsWith(" missing")).map(line => line.split(" ")[0]!); } -function failureSummary(error: unknown): string { - const text = error && typeof error === "object" && "stderr" in error ? String((error as { stderr?: unknown }).stderr ?? "") : String(error); - const line = text.split("\n").map(part => part.trim()).find(part => /^(fatal|error):/iu.test(part)) ?? text.split("\n")[0]?.trim() ?? ""; - // Never echo credentials embedded in remote URLs. - return line.replace(/\/\/[^/@\s]+@/gu, "//").slice(0, 200) || "fetch failed"; -} /** Download the contents of cited files that a partial clone has not fetched yet. * Only `update --pending` calls this; status, verify and production reads stay local. @@ -92,11 +87,12 @@ export async function prepareRepositoryContents(projectRoot: string, else { try { for (let index = 0; index < missing.length; index += FETCH_BATCH) { - await git(root, ["-c", "fetch.negotiationAlgorithm=noop", "fetch", "--no-tags", "--no-write-fetch-head", + // Runs as long as git reports progress; stalls and very long downloads are reported. + await runGitWithProgress(["-C", root, "-c", "fetch.negotiationAlgorithm=noop", "fetch", "--no-tags", "--no-write-fetch-head", "--recurse-submodules=no", "--filter=blob:none", remote, ...missing.slice(index, index + FETCH_BATCH)], - { env: { ...process.env, GIT_TERMINAL_PROMPT: "0" }, timeout: 120_000 }); + { env: { ...process.env, GIT_TERMINAL_PROMPT: "0" }, label: `git fetch of ${request.source_ref} contents` }); } - } catch (error) { result.reason = failureSummary(error); } + } catch (error) { result.reason = redactRemoteCredentials(error instanceof Error ? error.message : String(error)).slice(0, 400); } result.unresolved = (await missingObjects(root, commit, paths)).length; if (!result.unresolved) delete result.reason; } diff --git a/packages/context-cli/src/project/repoSourceRecovery.ts b/packages/context-cli/src/project/repoSourceRecovery.ts index 72a3b1be..5881b801 100644 --- a/packages/context-cli/src/project/repoSourceRecovery.ts +++ b/packages/context-cli/src/project/repoSourceRecovery.ts @@ -1,3 +1,4 @@ +import { GitProgressError, runGitWithProgress } from "../lib/gitProgress.js"; import { execFile } from "node:child_process"; import { existsSync } from "node:fs"; import { lstat, mkdir, readlink, realpath, rm, symlink } from "node:fs/promises"; @@ -268,20 +269,18 @@ async function cloneCheckout(input: { } await mkdir(dirname(target), { recursive: true }); const cloneArgs = ["clone", "--no-checkout", "--depth=1", "--filter=blob:none", input.remote, target]; + // Clones run while git reports progress. A stalled or very long clone is reported, not retried. + const clone = (args: string[]) => runGitWithProgress(args, { env: { ...process.env, GIT_TERMINAL_PROMPT: "0" }, label: "git clone" }); try { - await execFileAsync("git", cloneArgs, { encoding: "utf8", maxBuffer: 4 * 1024 * 1024 }); - } catch { + await clone(cloneArgs); + } catch (first) { await rm(target, { recursive: true, force: true }); try { - await execFileAsync("git", ["clone", "--no-checkout", "--depth=1", input.remote, target], { - encoding: "utf8", - maxBuffer: 4 * 1024 * 1024, - }); + if (first instanceof GitProgressError && first.kind !== "failed") throw first; + await clone(["clone", "--no-checkout", "--depth=1", input.remote, target]); } catch (error) { await rm(target, { recursive: true, force: true }); - const detail = error !== null && typeof error === "object" && "stderr" in error - ? String((error as { stderr?: unknown }).stderr ?? "").trim() - : error instanceof Error ? error.message : String(error); + const detail = error instanceof Error ? error.message : String(error); throw new ContextError(ExitCode.ExternalToolError, `cannot clone registered repository: ${input.remote}`, { category: ErrorCategory.ExternalToolFailed, remote: input.remote, @@ -292,9 +291,12 @@ async function cloneCheckout(input: { } try { try { - await git(target, ["fetch", "--depth=1", "--filter=blob:none", "origin", input.ref]); - } catch { - await git(target, ["fetch", "--depth=1", "origin", input.ref]); + await runGitWithProgress(["-C", target, "fetch", "--depth=1", "--filter=blob:none", "origin", input.ref], + { env: { ...process.env, GIT_TERMINAL_PROMPT: "0" }, label: "git fetch" }); + } catch (first) { + if (first instanceof GitProgressError && first.kind !== "failed") throw first; + await runGitWithProgress(["-C", target, "fetch", "--depth=1", "origin", input.ref], + { env: { ...process.env, GIT_TERMINAL_PROMPT: "0" }, label: "git fetch" }); } const sparseDirectories = input.subpaths.length > 0 && (await Promise.all( input.subpaths.map((subpath) => git(target, ["cat-file", "-t", `${input.ref}:${subpath}`])), diff --git a/packages/context-cli/src/project/sourceRemoval.ts b/packages/context-cli/src/project/sourceRemoval.ts index 28bc8645..383ddd88 100644 --- a/packages/context-cli/src/project/sourceRemoval.ts +++ b/packages/context-cli/src/project/sourceRemoval.ts @@ -109,6 +109,37 @@ async function yamlReferences(input: { return strings.some((value) => stringReferencesSource(value, input.source)); } +/** Same key as the SDK's `loadSourcesRegistry` exclusion (a global symbol, so any SDK copy sees it). */ +const SOURCES_REGISTRY_EXCLUSION = Symbol.for("c4a.context.sources-registry-exclusion"); + +function projectReferences(project: Awaited>["project"], source: RemovableSource): string[] { + const references: string[] = []; + project.sources.forEach((declared, index) => { + if (sourceIdentity(declared) === source.name) references.push(`project.sources[${index}]`); + }); + project.phases.forEach((phase, index) => { + const direct = "source" in phase && sourceIdentity(phase.source as ProjectSourceDefinition) === source.name; + const resource = phase.reads.some((read) => resourceReferencesSource(read, source)); + if (direct || resource) references.push(`project.phases[${index}] (${phase.id})`); + }); + return references; +} + +/** Project declarations that still name the source when its registry entry is left out + * are the project's own; those the entry builds from the registry go with the entry. + * An SDK without the exclusion, or a project that cannot load without the entry, keeps + * every declaration, as before. */ +async function declaredReferences(projectRoot: string, source: RemovableSource): Promise { + const global = globalThis as Record; + const previous = global[SOURCES_REGISTRY_EXCLUSION]; + global[SOURCES_REGISTRY_EXCLUSION] = new Set([source.name]); + let project; + try { project = (await loadContextProjectModule(projectRoot)).project; } + catch { project = undefined; } + finally { global[SOURCES_REGISTRY_EXCLUSION] = previous; } + return projectReferences(project ?? (await loadContextProjectModule(projectRoot)).project, source); +} + async function collectSourceReferences(projectRoot: string, source: RemovableSource): Promise { const references = new Set(); const { currentLedger, currentSpec } = await import("./indexerMainRunStoreRecords.js"); @@ -118,15 +149,7 @@ async function collectSourceReferences(projectRoot: string, source: RemovableSou const values: string[] = []; collectStrings(spec.request.workset, values); if (values.some((value) => stringReferencesSource(value, source))) references.add(`active Indexer ${entry.indexer_id}`); } - const loaded = await loadContextProjectModule(projectRoot); - loaded.project.sources.forEach((declared, index) => { - if (sourceIdentity(declared) === source.name) references.add(`project.sources[${index}]`); - }); - loaded.project.phases.forEach((phase, index) => { - const direct = "source" in phase && sourceIdentity(phase.source as ProjectSourceDefinition) === source.name; - const resource = phase.reads.some((read) => resourceReferencesSource(read, source)); - if (direct || resource) references.add(`project.phases[${index}] (${phase.id})`); - }); + for (const reference of await declaredReferences(projectRoot, source)) references.add(reference); for (const candidate of await readCandidateRecords(projectRoot)) { if ( diff --git a/packages/context-cli/src/project/status.ts b/packages/context-cli/src/project/status.ts index 20c3d12b..7cec057b 100644 --- a/packages/context-cli/src/project/status.ts +++ b/packages/context-cli/src/project/status.ts @@ -43,7 +43,7 @@ import { recordContextDebugPerformance, } from "./debugTrace.js"; import { observeContextRuntimeEventDelivery } from "../runtimeEvents.js"; -import { inspectWorkspaceVersion } from "./workspaceChangelog.js"; +import { inspectWorkspaceVersion, readWorkspaceChangelog } from "./workspaceChangelog.js"; import { pendingDocumentCaptureCommands, } from "./statusRouting.js"; @@ -143,7 +143,11 @@ async function collectProjectStatusSnapshotInternal( const authoring = production && !production.delivery && (dispatchProductionStage(production, productionCapabilitiesSchema.parse({})).state !== "ended" || (draftStatus.count > 0 && draftStatus.diagnostics.length === 0)); - const deferDeliveryChecks = !maintenance && !localRevision && !localUpdate && !localRollback && + // After delivery, a navigation-only edit (task adjust knowledge_map) is + // output-only work: record a version and build, without a new task. + const navigationOnly = !maintenance && !localRevision && !localUpdate && !localRollback && taskPreparation === "cleared" && + !production && phaseStatus.projectEntryValid && await navigationOnlyChange(projectRoot, phaseStatus.packages); + const deferDeliveryChecks = !maintenance && !localRevision && !localUpdate && !localRollback && !navigationOnly && ((taskPreparation === "cleared" && !production) || !!authoring); const collectionsWithPages = new Set(); const approvedPages = await countFiles( @@ -214,7 +218,7 @@ async function collectProjectStatusSnapshotInternal( const draftCollections = [...new Set(indexerDrafts.map((candidate) => candidate.collection))].sort(); // Output-only maintenance owns this evaluation; an unfinished production // ledger must not hide package configuration/Review recovery gates. - const maintenanceOutputOnly = maintenance?.input.operation === "rebuild" || maintenance?.phase === "finishing" || + const maintenanceOutputOnly = navigationOnly || maintenance?.input.operation === "rebuild" || maintenance?.phase === "finishing" || (maintenance?.phase === "cancelling" && indexerDrafts.length === 0); const sourceUpdate = !maintenance && !localRevision && !localUpdate && !localRollback && !production && draftStatus.count === 0 && approvedPages > 0 ? await import("./pendingSourceUpdates.js").then(({ inspectPendingSourceUpdates }) => inspectPendingSourceUpdates(projectRoot)) @@ -454,3 +458,31 @@ export async function collectProjectStatus( return (await collectProjectStatusSnapshot(projectRoot, options)).status; } import { withCommandReadCache } from "./commandReadCache.js"; + +/** A knowledge-map-only change still owes its version or build. Judged against the + * last version record, not the working tree: (1) since the commit that last recorded a + * version, the knowledge map changed and nothing else under knowledge/, sources/ or src/; or + * (2) the latest version records only navigation and its packages are not confirmed + * built. (1) takes a few Git calls; (2) runs the build freshness check only after a + * navigation-only version. */ +async function navigationOnlyChange(projectRoot: string, packages: Parameters[1]): Promise { + const { KNOWLEDGE_MAP_PATH } = await import("./knowledgeMap.js"); + const { excludedWorkspaceContent } = await import("./workspaceContentSnapshot.js"); + const { execFile } = await import("node:child_process"); + const git = (...args: string[]) => new Promise(done => execFile("git", ["-C", projectRoot, ...args], + { env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" }, timeout: 30_000, maxBuffer: 64 * 1024 * 1024 }, (error, stdout) => done(error ? undefined : stdout))); + const recorded = (await git("log", "-1", "--format=%H", "--", "changelog.yaml"))?.trim(); + if (recorded) { + const changed = [...(await git("diff", "--name-only", "--relative", recorded, "--"))?.split("\n") ?? [], + ...(await git("ls-files", "--others", "--exclude-standard"))?.split("\n") ?? []] + .filter(path => path && path !== "package.json" && !excludedWorkspaceContent(path)); + // Notes beside the workspace (README, TODO) do not need production; articles, sources and project code do. + if (changed.includes(KNOWLEDGE_MAP_PATH) && changed.every(path => path === KNOWLEDGE_MAP_PATH || !/^(?:knowledge|sources|src)\//u.test(path))) return true; + } + const latest = (await readWorkspaceChangelog(projectRoot).catch(() => []))[0]; + if (!latest || !latest.triggers.every(trigger => trigger.kind === "navigation")) return false; + // The build's own freshness check decides; a missing local build record is not a finished build. + const freshness = await readPackageFreshnessStatus(projectRoot, packages); + return freshness.diagnostics.length > 0 || freshness.packages.length < packages.length || + freshness.packages.some(item => item.state !== "ready"); +} diff --git a/packages/context-cli/src/project/submittedSourceLocator.ts b/packages/context-cli/src/project/submittedSourceLocator.ts index 50b6c1da..43741796 100644 --- a/packages/context-cli/src/project/submittedSourceLocator.ts +++ b/packages/context-cli/src/project/submittedSourceLocator.ts @@ -5,6 +5,21 @@ export const submittedSourceLocatorSchema = articleSourceLocatorInputSchema; export type SubmittedSourceLocator = ArticleSourceLocatorInput; export interface SubmittedSourceReference { source_ref: string; locator: SubmittedSourceLocator } +/** A capture gap's placeholder, as capture writes it, also inside a table cell: + * "> Resource unavailable: (<kind>; <reason>). <!-- <locator> -->". */ +const CAPTURE_GAP = /(?:> ?)?Resource unavailable: .+? \([^;()]+; [^()]+\)\. <!-- [^>]+ -->/u; + +/** A gap stands for missing content and cannot be evidence. A cited line that holds only + * gaps is rejected; a line with captured text besides the gap (a table row) stays citable. */ +export function assertNoCaptureGap(locator: ArticleSourceLocator, capturedText: string): void { + const lines = capturedText.replace(/\r\n/gu, "\n").split("\n").slice(locator.start_line - 1, locator.end_line); + const gapOnly = (line: string) => CAPTURE_GAP.test(line) && + line.replace(new RegExp(CAPTURE_GAP.source, "gu"), "").replace(/<br\s*\/?>|[|>\s]/giu, "") === ""; + const gap = lines.findIndex(gapOnly); + if (gap >= 0) throw new SubmissionInputError(`${locator.path}:${locator.start_line + gap} is a capture gap (the resource was not captured), ` + + "not evidence. Cite only captured lines; the missing content cannot support a claim until it is captured."); +} + /** Call only after authorization, with the same captured text used for hashing. */ export function resolveSubmittedSourceLocator(input: SubmittedSourceLocator, capturedText: string): ArticleSourceLocator { const locator = submittedSourceLocatorSchema.parse(input); diff --git a/packages/context-cli/src/project/workflow/workflowFacts.ts b/packages/context-cli/src/project/workflow/workflowFacts.ts index 2479ce31..1d65ee3e 100644 --- a/packages/context-cli/src/project/workflow/workflowFacts.ts +++ b/packages/context-cli/src/project/workflow/workflowFacts.ts @@ -148,7 +148,8 @@ export function createContextWorkflowFacts( return { workspace: { - task_start_authorized: observation.taskPreparation !== "cleared", + // Output-only work (a rebuild or a navigation change) needs no new task. + task_start_authorized: observation.taskPreparation !== "cleared" || outputOnlyMaintenance, project_entry_valid: observation.projectEntryValid, state_valid: workspaceStateValid(observation), }, diff --git a/packages/context/docs/guides/knowledge-updates.md b/packages/context/docs/guides/knowledge-updates.md index fb644fd5..e5fc1257 100644 --- a/packages/context/docs/guides/knowledge-updates.md +++ b/packages/context/docs/guides/knowledge-updates.md @@ -187,6 +187,13 @@ untagged version updates that description without changing its version or conten checkpoint. No additional flag is needed. If this session already published the version, record a new version instead: the CLI protects tagged records but cannot infer whether an untagged version was published by another tool. +To merge several unpublished intermediate versions into one entry, restore only +the version files (`package.json` version, `CHANGELOG.md`, `changelog.yaml`) to +the last published version and keep every knowledge change. Then run `version +inspect --base <that version's commit> --format json` and record one entry with +the returned digest and the same commit as `base_ref`. Never rewrite a version +already merged into the remote default branch (`merged_to`) or tagged; there is +no squash command. Publication belongs to the installed distribution tool. Record remote receipts in its configuration or the existing work summary, separately for each target. A successful authorized commit/tag identifies the delivered source; never create @@ -206,7 +213,9 @@ entry retains its stable key, parent, title and order; optional targets use article identity and section key. The current structure preview supplies those identities. Read the persistent `src/knowledge-map.yaml`; use `expected_revision: null` only when no knowledge map exists. -After adjustment, follow status to rebuild affected packages. This changes the +After adjustment, follow status to rebuild affected packages; once delivery has +finished, the Route records a patch version (`navigation` trigger) and builds, +without resuming production. This changes the reading organization without capturing sources or rewriting approved prose. Do not directly edit generated package navigation or use titles as identities. diff --git a/packages/context/docs/guides/lark-resources.md b/packages/context/docs/guides/lark-resources.md index 5e9e2885..ee857971 100644 --- a/packages/context/docs/guides/lark-resources.md +++ b/packages/context/docs/guides/lark-resources.md @@ -83,8 +83,15 @@ an explicit permission denial (including HTTP 403) for an embedded resource, Con `document.resource.permission-denied`, keeps the stable resource identity in the audit layer, renders the same unavailable-resource notice, and continues with a warning. Explicit missing-scope and access-denied resource responses are -likewise recorded without changing identity. Transient network errors, malformed -payloads, and unclassified failures still block capture. Reference-only +likewise recorded without changing identity, as is a synced block whose source +document the identity cannot open. Such gaps are listed in the capture result and +cannot be cited. To close one, request the missing app scope for the app at +https://open.larkoffice.com/app, or ask the document's owner to share it with +the capturing identity, then capture again. Transient network errors, malformed +payloads, and unclassified failures still block capture. When a refresh of an +unchanged revision turns a previously captured resource into such a gap or a +preview, the new snapshot is saved and the result lists the downgrade; a blocking +failure keeps the old snapshot, and a body that cannot be read never replaces it. Reference-only resources remain explicit in the capture report. Unknown non-empty XML blocks stay auditable in the raw XML and receive a warning; the CLI does not infer their meaning. diff --git a/packages/context/src/sources.ts b/packages/context/src/sources.ts index 98f90ef3..d8a75c8a 100644 --- a/packages/context/src/sources.ts +++ b/packages/context/src/sources.ts @@ -601,6 +601,10 @@ const assertGlobalSourceUniqueness = (registry: SourcesRegistry): void => { } }; +/** Set only by the CLI while it checks which project declarations the registry + * produces: entries with these names or ids are left out of the loaded registry. */ +export const SOURCES_REGISTRY_EXCLUSION = Symbol.for("c4a.context.sources-registry-exclusion"); + export const loadSourcesRegistry = async ( options: LoadSourcesRegistryOptions = {}, ): Promise<SourcesRegistry> => { @@ -612,6 +616,9 @@ export const loadSourcesRegistry = async ( const fileAbsolutePath = resolve(rootDir, fileRegistryPath); const larkAbsolutePath = resolve(rootDir, larkRegistryPath); + const excluded = (globalThis as Record<symbol, unknown>)[SOURCES_REGISTRY_EXCLUSION]; + const included = (entry: { id: string; name: string }) => + !(excluded instanceof Set && (excluded.has(entry.name) || excluded.has(entry.id))); const repoRegistry = parseRepoSourcesRegistry( await readYamlIfPresent(repoAbsolutePath, { sources: [] }), repoRegistryPath, @@ -638,9 +645,9 @@ export const loadSourcesRegistry = async ( file: fileAbsolutePath, lark: larkAbsolutePath, }, - repos: repoRegistry.repos, - files, - larks, + repos: repoRegistry.repos.filter(included), + files: files.filter(included), + larks: larks.filter(included), notes: await discoverManagedDocuments(rootDir, "note"), sessions: await discoverManagedDocuments(rootDir, "sessions"), };