Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 <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
Expand All @@ -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.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 <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
Expand All @@ -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.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -62,15 +62,19 @@ Write results under the returned Agent directory. All submission paths are
relative to `.tmp/agent-work/production-stages/<stage>/`, 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
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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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). <!-- block-1 -->\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). <!-- lark:whiteboard:w1 --> |",
"| | > Resource unavailable: Whiteboard (whiteboard; export permission denied). <!-- lark:whiteboard:w2 --><br><br> |", ""].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 }); }
});
26 changes: 26 additions & 0 deletions packages/context-cli/src/__tests__/checkoutMatchesCommit.test.ts
Original file line number Diff line number Diff line change
@@ -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);
});
12 changes: 12 additions & 0 deletions packages/context-cli/src/__tests__/cliEpipe.test.ts
Original file line number Diff line number Diff line change
@@ -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");
});
59 changes: 59 additions & 0 deletions packages/context-cli/src/__tests__/gitProgress.test.ts
Original file line number Diff line number Diff line change
@@ -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");
});
Loading
Loading