@c4a/context 0.6.3 → 0.6.5

package/README.md

@@ -67,6 +67,21 @@ code extractor. Use `customPhase()` only for orchestration that does not publish
 knowledge candidates; it is not a replacement for source, extraction, Review,
 and package lifecycle rules.
 
+Context CLI intentionally does not bundle every language or repository parser.
+Optional structural libraries can be installed by the knowledge project and
+used inside `extractCustom()`:
+
+| Package | Structural facts |
+|---|---|
+| `@c4a/extract-go` | Go declarations, imports, calls, and common HTTP route registrations |
+| `@c4a/extract-rush` | Rush projects, tags, entry signals, workspace dependencies, and owner boundaries |
+| `@c4a/extract-ts` | TypeScript extraction plus reusable React Router route facts |
+
+These libraries do not create Context phases or candidates by themselves. The
+project maps their deterministic facts to its own candidate identities and
+review summaries; Context continues to own evidence validation, freshness,
+Review, close, and package output.
+
 ## Knowledge Collections
 
 Approved Markdown is organized under `knowledge/<collection>/`:
@@ -126,6 +141,15 @@ it is not repeated inside knowledge paths. Context still accepts
 no longer changes build output and new declarations do not need it. Skill names
 remain author-maintained and independent.
 
+New KB setup should offer `assets: { delivery: "git-raw" }` first. Build
+rewrites resource links to Git raw URLs; committing and publishing the resource
+files remains the package author's responsibility. Non-Git workspaces may use
+an explicit `urlPrefix`; without one they can bundle resources or explicitly
+omit them and retain unresolved references. Bundled delivery may
+install `sharp` in the workspace and configure `assets.optimize`; Context
+itself has no image dependency and never changes source snapshots or approved
+resources.
+
 For advanced routing and retrieval, a template may carry a local script such as
 `query.ts`, with a Skill describing when and how an Agent should call it. The
 Skill can also route the Agent to MCP servers, CLI commands, or other tools to

package/README.zh-CN.md

@@ -57,6 +57,18 @@ export default defineProject({
 非 TypeScript 或需要聚合代码事实时使用 `extractCustom()`。`customPhase()`
 只用于不发布知识候选的项目专用编排，不能绕开来源、提取、审核和打包生命周期。
 
+Context CLI 不会把所有语言和仓库解析器都打入自身。知识项目可以按需安装结构
+提取库，并在 `extractCustom()` 中使用：
+
+| 包 | 提供的结构事实 |
+|---|---|
+| `@c4a/extract-go` | Go 声明、导入、调用和常见 HTTP 路由注册 |
+| `@c4a/extract-rush` | Rush 项目、标签、入口信号、工作区依赖和所有者边界 |
+| `@c4a/extract-ts` | TypeScript 提取，以及可复用的 React Router 路由事实 |
+
+这些库本身不会创建 Context 阶段或候选。项目负责把确定性事实映射为自己的候选
+身份和审核摘要；证据校验、新鲜度、审核、close 和打包仍由 Context 管理。
+
 ## 知识分类
 
 审核通过的 Markdown 会存放在 `knowledge/<collection>/`：
@@ -104,6 +116,13 @@ kb/
 `distribution.knowledgeNamespace` 仍可被读取，但不再改变构建结果；新声明无需配置它。
 Skill 名称继续由作者独立维护。
 
+新建 KB 时优先选择 `assets: { delivery: "git-raw" }`：构建器把资源链接改写到
+Git raw 地址；资源的提交和发布由知识包作者负责，Context 不做远端探测。
+非 Git 工作区也可以配置显式 `urlPrefix`，引用另一个仓库已经发布的资源；没有
+可用 Git 或显式前缀时，可选择 `delivery: "bundle"` 随包分发，或显式选择
+`delivery: "omit"` 不输出资源并保留失效引用。随包分发还可以在工作区安装 `sharp` 并通过
+`assets.optimize` 仅优化生成的知识包；Context 本身不依赖图片处理库。
+
 如果需要更强的路由和检索能力，模板可以携带 `query.ts` 一类本地脚本，再由 Skill 约定 Agent 何时、如何调用。Skill 也可以把 Agent 路由到 MCP、CLI 或其他工具，组成适合当前知识包的 Agentic Search 流程。
 
 长期维护、多来源的知识生产工作区可以从

package/docs/README.md

@@ -19,6 +19,7 @@ general reference; do not preload the whole manual set.
 - [Package Outputs](./guides/package-outputs.md) — how to choose between an agent knowledge-base package, LLM text, or no package output.
 - [Lark Resource Materialization](./guides/lark-resources.md) — how embedded resources move from source evidence to approved knowledge and package assets.
 - [Project API](./reference/project-api.md) — `defineProject`, sources, phases, review, and packages.
+- [Code Extractor Selection](./reference/code-extractors.md) — inspect module technology signals and choose a built-in extractor, reusable structural package, or project adapter.
 - [Package Templates](./reference/package-templates.md) — `kbPackage`, `llmsPackage`, template variables, and examples.
 - [Template Variables](./reference/template-variables.md) — Handlebars variables, loops, comments, and default knowledge inventories.
 

package/docs/guides/agent-guide.md

@@ -72,6 +72,13 @@ node_modules/@c4a/context/docs/reference/project-api.md
 node_modules/@c4a/context/docs/reference/package-templates.md
 ```
 
+When configuring code extraction, use the Route-selected
+`reference/code-extractors.md` manual. Run the Gate's read-only source
+inspection first, use its manifest signals to select a matching extractor, and
+read that package's public README before implementing an `extractCustom()`
+adapter. Do not probe compiled package output or treat TypeScript as the default
+for a non-TypeScript module.
+
 ## Workspace State Rules
 
 - `src/index.ts` declares sources, phases, and packages.

package/docs/guides/package-outputs.md

@@ -90,11 +90,25 @@ task workflows. Authors may explicitly accept the generic default when it is
 intentionally sufficient.
 
 When approved pages reference materialized document resources, Context keeps
-their production copies in content-addressed `knowledge/assets/` paths. Build
-copies only the resources selected by package pages to `others/assets/` and
-rewrites relative Markdown links. Source audit XML and capture reports stay in
-the production workspace; they are not distributed as reader assets. See
-[Lark Resource Materialization](./lark-resources.md).
+their production copies in content-addressed `knowledge/assets/` paths. New KB
+setup should offer Git raw delivery first. It rewrites package links to either
+an automatically derived raw prefix or an explicit author-provided prefix.
+Context does not check whether resource files are committed, pushed, or
+remotely readable; that is the package author's responsibility. With no
+explicit prefix, supported remotes use an immutable commit URL. An explicit
+prefix can contain `{commit}` when the Context workspace is in Git, or name a
+mutable branch when that lifecycle is intentional; a literal prefix also works
+when resources are published from a separate repository.
+
+Workspaces without usable Git or an explicit raw prefix can choose bundled
+delivery, which copies only selected resources to `others/assets/`, or explicit
+omission, which does not copy resources and reports that links remain
+unresolved. Bundled output may
+optionally install `sharp` in the workspace and configure
+`assets.optimize`; Context itself has no image dependency. Optimization changes
+only `dist/`, content-addresses smaller WebP output, and leaves `sources/` and
+`knowledge/assets/` unchanged. Source audit XML and capture reports are never
+distributed as reader assets. See [Lark Resource Materialization](./lark-resources.md).
 
 The same inventory exposes `structure.relationship_coverage`. It records
 whether selected codegraph pages have current source-backed AST relationship

package/docs/reference/code-extractors.md

@@ -0,0 +1,88 @@
+# Code Extractor Selection
+
+Use this manual only when the current code-extraction Route asks the Agent to
+choose or declare an extractor. The CLI reports repository facts; the Agent
+chooses how those facts become source-backed code knowledge.
+
+## Inspect Before Declaring
+
+Run every read-only inspection command returned by the extraction-scope Gate.
+The result identifies each confirmed module and its recognized `manifests`.
+Treat these as deterministic technology signals, not as product semantics:
+
+| Signal | Technology candidate |
+|---|---|
+| `package.json` | TypeScript, TSX, JavaScript, or JSX |
+| `go.mod` | Go |
+| `Cargo.toml` | Rust |
+| `pyproject.toml` or `setup.py` | Python |
+| `pom.xml` or `build.gradle` | Java or JVM |
+| multiple manifests | a mixed module that may need more than one extractor |
+
+Do not select `extractTs()` merely because a repository contains some
+TypeScript. Decide against the exact confirmed module and include boundary. A
+mixed module may compose multiple structural passes; parser selection is not an
+exclusive repository-wide switch.
+
+## Selection Order
+
+Use the narrowest reusable capability that covers the confirmed source:
+
+1. Use a Context-owned phase when its contract matches the source.
+2. Otherwise use a reusable structural package inside `extractCustom()`.
+3. If no reusable package covers the syntax or repository protocol, implement a
+   project-owned adapter and keep it in the Context workspace.
+
+Current reusable capabilities are:
+
+| Source fact | Preferred capability | Lifecycle integration |
+|---|---|---|
+| TypeScript/TSX package or file scope | `extractTs()` | Context-owned phase |
+| Go declarations, imports, calls, and common HTTP routes | `@c4a/extract-go` | call from `extractCustom()` |
+| Rush workspace packages, tags, dependencies, entries, and owners | `@c4a/extract-rush` | call from `extractCustom()`; may complement a language extractor |
+| React Router route declarations | `extractReactRouterRoutes()` from `@c4a/extract-ts` | call from `extractCustom()`; complements TypeScript symbols |
+| Rust, Python, Java/JVM, or an unsupported framework/protocol | no assumed built-in parser | project-owned `extractCustom()` adapter |
+
+An optional package does not create a new CLI phase. Add it as an explicit
+workspace dependency, then map its structural facts to candidates in the
+project callback. Do not add a parser package when its documented coverage does
+not match the inspected source.
+
+## Read The Contract Before Extending
+
+Before editing `src/index.ts`, read the relevant installed public manual or
+package README. Do not infer APIs from bundled JavaScript.
+
+- Context lifecycle and `extractCustom()`:
+  `node_modules/@c4a/context/docs/reference/project-api.md`
+- Generic plugin protocol:
+  `node_modules/@c4a/extract/README.md`
+- TypeScript:
+  `node_modules/@c4a/extract-ts/README.md`
+- Go:
+  `node_modules/@c4a/extract-go/README.md`
+- Rush:
+  `node_modules/@c4a/extract-rush/README.md`
+
+If an optional package is not installed, use this capability matrix to decide
+whether it is relevant, add only that dependency, and then read its shipped
+README before implementing the callback.
+
+A project-owned adapter may use an existing parser, compiler API, or command
+whose output is deterministic. It must return source-backed candidates through
+`extractCustom()`; it must not write lifecycle, knowledge, or Review files.
+Framework-specific classification and rendering remain in the project. The CLI
+and structural parser must not infer product meaning.
+
+## Decision To Report
+
+Before the first extraction preview, state briefly:
+
+- the inspected module and manifest signals;
+- the selected Context phase or structural package;
+- whether coverage is complete or which facts remain project-owned; and
+- why another available extractor is not needed.
+
+If no current capability can parse the source reliably, stop at configuration
+and report the missing generic capability. Do not silently emit an empty
+codegraph or reuse an unrelated parser.

package/docs/reference/package-templates.md

@@ -31,6 +31,10 @@ kbPackage({
     foldDirectoryIndexes: true,
     maxInlineEntries: 50,
   },
+  assets: {
+    delivery: "git-raw",
+    urlPrefix: "https://code.example.com/team/knowledge/raw/{commit}",
+  },
 });
 ```
 
@@ -52,8 +56,67 @@ llmsPackage({
 | `template` | yes | Project-relative template directory or `{ path, vars }`. |
 | `select` | no | Approved knowledge selector. Omit to include all approved knowledge. Supports internal `collections`, OKF `okfRoots`, and `include` / `exclude` path patterns relative to `knowledge/`. |
 | `navigation` | no | KB directory-index policy. Defaults to `{ foldDirectoryIndexes: true, maxInlineEntries: 50 }`. |
+| `assets` | no | Resource delivery: Git raw links, bundled files, or explicit omission. New KB setup should offer Git raw first. Omit for legacy byte-for-byte bundling. |
 | `distribution` | no | Legacy input accepted from older workspaces. It no longer changes package paths and should not be added to new declarations. |
 
+Use Git raw delivery when resources are published from a Git repository.
+Without `urlPrefix`, the Context workspace must be inside Git; GitHub remotes
+are derived automatically and pinned to the current commit. Other hosts accept
+an explicit HTTPS prefix. `{commit}` is replaced only when the workspace is
+inside Git, because Context must resolve the current commit. A workspace outside
+Git must use a literal, already-published prefix without `{commit}`. Context
+appends the project-relative `knowledge/assets/...` path.
+
+The resolved commit and raw URL participate in package freshness, so changing
+Git HEAD or the selected remote makes an existing package stale. Context does
+not check whether resources are committed, pushed, or remotely readable;
+publishing them is the package author's responsibility. A literal branch in the
+prefix is allowed but intentionally follows that mutable branch. The configured
+raw host must be reachable by the eventual package consumers.
+
+```ts
+assets: {
+  delivery: "git-raw",
+  urlPrefix: "https://code.example.com/team/knowledge/raw/{commit}",
+}
+```
+
+Outside Git, use a literal published prefix or choose bundled delivery or
+explicit omission:
+
+```ts
+assets: {
+  delivery: "git-raw",
+  urlPrefix: "https://code.example.com/team/knowledge/raw/published-assets",
+}
+```
+
+```ts
+assets: { delivery: "bundle" }
+assets: { delivery: "omit" } // keeps unresolved links and reports them
+```
+
+Bundled resources are copied byte-for-byte unless image optimization is
+configured. When optimizable PNG/JPEG resources exceed 20 MiB, build and status
+return `package.assets.optimization-recommended`. To optimize bundled output:
+
+```bash
+bun add -D sharp
+```
+
+```ts
+assets: {
+  delivery: "bundle",
+  optimize: { processor: "sharp", mode: "lossless-webp" },
+}
+```
+
+`optimize.mode: "webp"` additionally accepts `quality` from 1 to 100. Both modes accept
+an optional positive `maxDimension`; images are never enlarged. Context adopts
+a generated image only when it is smaller, uses a digest-derived `.webp` path,
+and rewrites package links. A configured but missing processor blocks before
+the previous `dist/` package is replaced.
+
 `template` is required. Do not call `kbPackage({ name })` or
 `llmsPackage({ name })`.
 

package/docs/reference/project-api.md

@@ -739,6 +739,41 @@ Review summary and source-backed evidence). It must not write `knowledge/`,
 Review snapshots directly. Context owns those files and preserves rejected and
 unchanged-approved decisions across reruns.
 
+#### Optional structural extractors
+
+For the manifest-to-capability decision and unsupported-language extension
+boundary, read [Code Extractor Selection](./code-extractors.md) before declaring
+the phase.
+
+`extractCustom()` may consume optional community packages without making them
+Context CLI dependencies:
+
+```ts
+import { indexGoRepository } from "@c4a/extract-go";
+import { extractCustom } from "@c4a/context";
+
+extractCustom({
+  id: "extract:service:codegraph",
+  sources: [service],
+  collection: "codegraph",
+  extract: async ({ projectRoot }) => {
+    const facts = await indexGoRepository(resolveServiceCheckout(projectRoot));
+    return { candidates: buildServiceCandidates(facts) };
+  },
+});
+```
+
+Available structural libraries include:
+
+- `@c4a/extract-go`: Go declarations, imports, calls, and common HTTP routes;
+- `@c4a/extract-rush`: Rush projects, tags, entries, dependencies, and owners;
+- `@c4a/extract-ts`: TypeScript extraction and `extractReactRouterRoutes()`.
+
+The packages return syntax and repository facts only. They do not classify
+product meaning, choose candidate identities, or write lifecycle state. The
+knowledge project owns that mapping. Context CLI does not auto-install these
+packages and does not expose a built-in Go or Rush phase.
+
 ### `reviewValidity`
 
 Declare the review step for a collection:

package/index.d.ts

@@ -22,6 +22,32 @@ export type PackageDistributionDefinition = {
     /** @deprecated Accepted for older workspaces; package output roots are flat. */
     knowledgeNamespace: string;
 };
+export type PackageAssetOptimizationDefinition = {
+    /** Image codec provider resolved from the Context workspace. */
+    processor: "sharp";
+    /** Lossless is the safe default; lossy WebP must be selected explicitly. */
+    mode?: "lossless-webp" | "webp";
+    /** WebP quality for lossy mode. */
+    quality?: number;
+    /** Optional longest-edge limit. Images are never enlarged. */
+    maxDimension?: number;
+};
+export type PackageAssetDefinition = {
+    /** Publish references to immutable Git-hosted resources instead of copying resource bytes. */
+    delivery: "git-raw";
+    /** Git remote used to derive the repository URL. */
+    remote?: string;
+    /** Optional HTTPS raw root. Context appends knowledge/assets/**; {commit} is supported. */
+    urlPrefix?: string;
+} | {
+    /** Copy resources into the package. */
+    delivery: "bundle";
+    /** Optional image optimization, resolved from the Context workspace. */
+    optimize?: PackageAssetOptimizationDefinition;
+} | {
+    /** Do not copy resources. Existing relative references remain unresolved. */
+    delivery: "omit";
+};
 export type BasePackageDefinition = {
     name: string;
     reads: readonly PhaseResourceReference[];
@@ -34,6 +60,7 @@ export type KbPackageDefinition = BasePackageDefinition & {
     kind: "package.kb";
     navigation: PackageNavigationDefinition;
     distribution?: PackageDistributionDefinition;
+    assets?: PackageAssetDefinition;
 };
 export type LlmsPackageDefinition = BasePackageDefinition & {
     kind: "package.llms";
@@ -55,6 +82,7 @@ export declare const kbPackage: (definition: {
     select?: PackageSelectDefinition;
     navigation?: Partial<PackageNavigationDefinition>;
     distribution?: PackageDistributionDefinition;
+    assets?: PackageAssetDefinition;
 }) => KbPackageDefinition;
 export declare const llmsPackage: (definition: {
     name: string;

package/index.js

@@ -11914,6 +11914,58 @@ var normalizePackageDistribution = (distribution) => {
   }
   return { knowledgeNamespace };
 };
+var normalizePackageAssetOptimization = (assets) => {
+  if (assets.processor !== "sharp") {
+    throw new TypeError(`Package assets.optimize.processor must be "sharp": ${String(assets.processor)}`);
+  }
+  const mode = assets.mode ?? "lossless-webp";
+  if (mode !== "lossless-webp" && mode !== "webp") {
+    throw new TypeError(`Package assets.optimize.mode must be "lossless-webp" or "webp": ${String(mode)}`);
+  }
+  if (assets.quality !== undefined && (!Number.isSafeInteger(assets.quality) || assets.quality < 1 || assets.quality > 100)) {
+    throw new TypeError(`Package assets.optimize.quality must be a safe integer from 1 to 100: ${assets.quality}`);
+  }
+  if (mode === "lossless-webp" && assets.quality !== undefined) {
+    throw new TypeError('Package assets.optimize.quality is only valid when assets.optimize.mode is "webp".');
+  }
+  if (assets.maxDimension !== undefined && (!Number.isSafeInteger(assets.maxDimension) || assets.maxDimension < 1)) {
+    throw new TypeError(`Package assets.optimize.maxDimension must be a positive safe integer: ${assets.maxDimension}`);
+  }
+  return {
+    processor: "sharp",
+    mode,
+    ...assets.quality === undefined ? {} : { quality: assets.quality },
+    ...assets.maxDimension === undefined ? {} : { maxDimension: assets.maxDimension }
+  };
+};
+var normalizePackageAssets = (assets) => {
+  if (assets === undefined)
+    return;
+  if (assets.delivery === "bundle") {
+    return {
+      delivery: "bundle",
+      ...assets.optimize === undefined ? {} : { optimize: normalizePackageAssetOptimization(assets.optimize) }
+    };
+  }
+  if (assets.delivery === "omit")
+    return { delivery: "omit" };
+  if (assets.delivery !== "git-raw") {
+    throw new TypeError(`Package assets.delivery must be "git-raw", "bundle", or "omit": ${String(assets.delivery)}`);
+  }
+  const remote = assets.remote?.trim();
+  if (remote !== undefined && !/^[A-Za-z0-9._-]+$/u.test(remote)) {
+    throw new TypeError(`Package assets.remote must be a safe Git remote name: ${assets.remote}`);
+  }
+  const urlPrefix = assets.urlPrefix?.trim().replace(/\/+$/u, "");
+  if (urlPrefix !== undefined && !urlPrefix.startsWith("https://")) {
+    throw new TypeError("Package assets.urlPrefix must be an HTTPS URL; it may contain {commit}.");
+  }
+  return {
+    delivery: "git-raw",
+    ...remote === undefined ? {} : { remote },
+    ...urlPrefix === undefined ? {} : { urlPrefix }
+  };
+};
 var assertSelectOkfRoots = (roots) => {
   for (const root of roots) {
     assertOkfRoot(root, "Package select.okfRoots");
@@ -11959,11 +12011,13 @@ var createPackageDefinitionBase = (kind, definition) => {
 var kbPackage = (definition) => {
   const base = createPackageDefinitionBase("kb", definition);
   const distribution = normalizePackageDistribution(definition.distribution);
+  const assets = normalizePackageAssets(definition.assets);
   return {
     kind: "package.kb",
     ...base,
     navigation: normalizePackageNavigation(definition.navigation),
-    ...distribution === undefined ? {} : { distribution }
+    ...distribution === undefined ? {} : { distribution },
+    ...assets === undefined ? {} : { assets }
   };
 };
 var llmsPackage = (definition) => ({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4a/context",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "type": "module",
   "description": "Context SDK — project-local configuration and workspace primitives",
   "license": "MIT",