orchestrator-workflow 0.40.1 → 0.42.0

package/dist/doctor.js

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { PACKAGE_VERSION } from "./assets.js";
-import { MANIFEST_PATH, readInstalledManifest } from "./init.js";
+import { MANIFEST_PATH, knowledgeEntryProblems, readInstalledManifest, } from "./init.js";
 import { DEFAULT_MODELS, rolesForProfile } from "./models.js";
 import { compareRoutingState } from "./routing-state.js";
 import { OPERATOR_MANIFEST_FILENAME, operatorManifestState, updateOperatorManifest, } from "./operator-manifest.js";
@@ -17,6 +17,9 @@ export function targetReportToJson(report) {
         ...(report.routingComparisonGaps?.length
             ? { routingComparisonGaps: report.routingComparisonGaps }
             : {}),
+        ...(report.knowledgeWarnings?.length
+            ? { knowledgeWarnings: report.knowledgeWarnings }
+            : {}),
         versionLag: report.versionLag,
         reason: report.reason,
     };
@@ -111,6 +114,61 @@ function computeDriftFiles(targetPath, manifest) {
     }
     return drifted;
 }
+/** The kit-wide implicit default knowledge-bundle location every site falls
+ * back to when a target configures no `knowledge` list at all. */
+const DEFAULT_KNOWLEDGE_PATH = "docs/okf";
+/** The raw `knowledge` value of a target's manifest file, before
+ * `readInstalledManifest` drops invalid entries; `undefined` when the field
+ * is absent or the file cannot be re-read. */
+function readRawKnowledge(targetPath) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(targetPath, MANIFEST_PATH), "utf8"));
+        if (typeof parsed !== "object" || parsed === null)
+            return undefined;
+        return parsed.knowledge;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isDirectoryAt(path) {
+    const stat = statOrClassify(path);
+    return stat.kind === "ok" && stat.stat.isDirectory();
+}
+/**
+ * Checks a target's configured `knowledge` list against its own filesystem.
+ * Each raw entry `readInstalledManifest` dropped as malformed is reported
+ * with its index and reason. For each kept entry, `path` and `repoRoot` are
+ * resolved against the target's top level independently (the manifest's
+ * model; `path` is not nested under `repoRoot`) and each one that is not a
+ * directory is reported by name. A non-empty list whose normalised `path`s
+ * omit an existing `docs/okf/` at the target's root (the implicit default
+ * every kit site assumes absent a `knowledge` field) is reported once.
+ * Absent or empty `knowledge` is today's default behaviour and never warns
+ * about `docs/okf/`: a repo that never configured `knowledge` is not warned
+ * about lacking an entry for its own default.
+ */
+function computeKnowledgeWarnings(targetPath, manifest) {
+    const knowledge = manifest.knowledge ?? [];
+    const warnings = knowledgeEntryProblems(readRawKnowledge(targetPath));
+    for (const bundle of knowledge) {
+        if (!isDirectoryAt(join(targetPath, bundle.path))) {
+            warnings.push(`missing configured knowledge path: ${bundle.path}`);
+        }
+        if (bundle.repoRoot !== "." &&
+            !isDirectoryAt(join(targetPath, bundle.repoRoot))) {
+            warnings.push(`missing configured knowledge repoRoot: ${bundle.repoRoot}`);
+        }
+    }
+    if (knowledge.length > 0) {
+        const docsOkfExists = isDirectoryAt(join(targetPath, DEFAULT_KNOWLEDGE_PATH));
+        const docsOkfConfigured = knowledge.some((bundle) => bundle.path === DEFAULT_KNOWLEDGE_PATH);
+        if (docsOkfExists && !docsOkfConfigured) {
+            warnings.push(`${DEFAULT_KNOWLEDGE_PATH}/ exists but is not in the configured knowledge list`);
+        }
+    }
+    return warnings;
+}
 function baseReport(target, operator, status, reason) {
     return {
         path: target.path,
@@ -210,6 +268,7 @@ export function inspectTarget(target, operator, kitVersion) {
     const versionLag = hasPin
         ? manifest.pin !== manifest.version
         : manifest.version !== kitVersion;
+    const knowledgeWarnings = computeKnowledgeWarnings(target.path, manifest);
     let status;
     if (driftFiles.length > 0) {
         status = "drift";
@@ -236,6 +295,7 @@ export function inspectTarget(target, operator, kitVersion) {
         ...(routingComparison.gaps.length > 0
             ? { routingComparisonGaps: routingComparison.gaps }
             : {}),
+        ...(knowledgeWarnings.length > 0 ? { knowledgeWarnings } : {}),
         repoProfile: manifest.profile,
         operatorProfile: operator.defaults.profile,
         repoTiers: manifest.tiers,

package/dist/init.d.ts

@@ -70,6 +70,32 @@ export interface InitOptions {
      * too, the same as `null`.
      */
     pin?: string | null;
+    /**
+     * Configured knowledge-bundle locations, or `undefined` to carry the
+     * previous manifest's `knowledge` forward unchanged (the same
+     * omitted-means-sticky convention `routing`/`pin` already use). A present
+     * array (including `[]`) replaces the previous value outright and is
+     * validated with {@link validateKnowledgeBundles}: an invalid entry throws
+     * rather than writing a malformed record. Absent (never set on any
+     * install) or `[]` means today's behaviour: `docs/okf/` is the sole,
+     * implicit bundle location every kit site assumes. The CLI has no flag for
+     * this; operators hand-edit the manifest field instead.
+     */
+    knowledge?: KnowledgeBundle[];
+}
+/**
+ * One configured knowledge-bundle location. `path` is the bundle directory
+ * (for example `docs/okf`) and `repoRoot` the root of the repository the
+ * bundle's sources live in (`"."` when that is the worktree itself, a
+ * sub-repo's path for a workspace-level bundle whose sources live
+ * elsewhere). Each is resolved against the worktree top level on its own:
+ * `path` is not nested under `repoRoot`. Both are stored normalised
+ * (see {@link checkKnowledgeEntry}) and must not escape the worktree top
+ * level; no check argv lives here (see verification-set docs).
+ */
+export interface KnowledgeBundle {
+    path: string;
+    repoRoot: string;
 }
 export declare const MANIFEST_PATH: string;
 export interface Manifest extends OpencodeModelMaps {
@@ -114,6 +140,25 @@ export interface Manifest extends OpencodeModelMaps {
      * recorded" and therefore never sticky.
      */
     harnessesRecordedEmpty?: boolean;
+    /**
+     * Configured knowledge-bundle locations. Absent when never configured on
+     * any install of this repo: every kit site that reads this field then
+     * falls back to the implicit `docs/okf/` default, today's behaviour; an
+     * empty list means the same. When present, an entry that fails
+     * validation (a non-relative or top-level-escaping `path`/`repoRoot`) is
+     * dropped rather than carried forward, the same per-entry degradation
+     * style `files`/`models` above already use for a hand-written or damaged
+     * manifest; `doctor` reports each dropped entry, and a re-install that
+     * rewrites the manifest notes each one it removes from disk.
+     */
+    knowledge?: KnowledgeBundle[];
+    /**
+     * The {@link knowledgeEntryProblems} of the raw on-disk `knowledge` value,
+     * set by `readInstalledManifest` only when there is at least one. Never
+     * written back: `runInit` turns each into a report note when it rewrites
+     * the manifest and so removes the offending value from disk.
+     */
+    knowledgeProblems?: string[];
 }
 /**
  * A manifest can be hand-written or tampered with, and uninstall deletes by
@@ -122,6 +167,38 @@ export interface Manifest extends OpencodeModelMaps {
  * can never reach an unlink.
  */
 export declare function isContainedRelativePath(relativePath: string): boolean;
+/**
+ * Checks one raw `knowledge` entry. `path` (the bundle directory) and
+ * `repoRoot` (the root of the repository its sources live in) are each
+ * resolved against the worktree top level, independently of one another, so
+ * a workspace-level bundle whose sources live in a sub-repo is
+ * `{ path: "docs/okf", repoRoot: "sub" }`. `repoRoot` defaults to `"."`
+ * when omitted. Returns the normalised entry, or the reason it is invalid
+ * (naming the offending field) for the caller to throw or report.
+ */
+export declare function checkKnowledgeEntry(entry: unknown): {
+    bundle: KnowledgeBundle;
+} | {
+    reason: string;
+};
+/**
+ * Lists every problem in a raw on-disk `knowledge` value: `[]` when the
+ * field is absent or every entry is valid, one item for a non-array value,
+ * otherwise one item per invalid entry with its index and reason. `doctor`
+ * reports these, since {@link parseKnowledgeBundles} drops such entries on
+ * read; `runInit` reports them as notes when a re-install that carries
+ * `knowledge` forward rewrites the manifest and so removes them from disk.
+ */
+export declare function knowledgeEntryProblems(raw: unknown): string[];
+/**
+ * Validates an explicitly-supplied `options.knowledge` array for `runInit`
+ * with {@link checkKnowledgeEntry} and returns the normalised entries.
+ * Throws on the first invalid entry -- explicit input refuses to write a
+ * malformed record rather than dropping it (contrast
+ * {@link parseKnowledgeBundles}, which degrades a hand-edited/damaged
+ * on-disk manifest by dropping bad entries instead of throwing).
+ */
+export declare function validateKnowledgeBundles(knowledge: unknown): KnowledgeBundle[];
 /**
  * Reads the manifest of a previous install, if any. Manifests can be written
  * by hand (manual agent installs) or damaged, so every field is sanitized;

package/dist/init.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, statSync } from "node:fs";
-import { isAbsolute, join, normalize, sep } from "node:path";
+import { isAbsolute, join, normalize, posix, sep, win32 } from "node:path";
 import { PACKAGE_VERSION, listSkillReferenceNames, listTemplateNames, readAgentAsset, readAsset, } from "./assets.js";
 import { HARNESSES } from "./detect.js";
 import { CLASS_MODELS, DEFAULT_PROFILE, DEFAULT_TIER, READ_ONLY_ROLES, ROLES, ROLE_TIERS, TIER_DEFS, assertValidModelId, claudeModelValue, isProfile, opencodeModelValue, rolesForProfile, } from "./models.js";
@@ -25,6 +25,155 @@ export function isContainedRelativePath(relativePath) {
     const normalized = normalize(relativePath);
     return normalized !== ".." && !normalized.startsWith(`..${sep}`);
 }
+/**
+ * The containment problem of one knowledge-bundle path spelling, or
+ * `undefined` when it stays inside the worktree top level: an absolute path
+ * (native, POSIX, or Windows such as `C:/x`), any other value starting with
+ * a Windows drive letter (the drive-relative `C:x`, `C:..` or `C:`, which
+ * Windows resolves against that drive's current directory), or a `..`
+ * escape. The `..` test is only meaningful on a normalised value.
+ */
+function knowledgePathContainmentProblem(value) {
+    if (isAbsolute(value) || posix.isAbsolute(value) || win32.isAbsolute(value)) {
+        return "is an absolute path";
+    }
+    if (/^[A-Za-z]:/.test(value))
+        return "is a Windows drive path";
+    if (value === ".." || value.startsWith("../")) {
+        return "escapes the worktree top level";
+    }
+    return undefined;
+}
+/**
+ * Normalises one knowledge-bundle path field (`path` or `repoRoot`) and
+ * returns it, or a reason string when it is not acceptable. Both fields are
+ * worktree-relative, so spellings of the same location compare equal after
+ * this step: POSIX `normalize`, then any trailing `/` stripped (`docs/okf/`,
+ * `./docs/okf` and `docs/okf` all become `docs/okf`). An empty string, any
+ * backslash, and every value with a
+ * {@link knowledgePathContainmentProblem} are rejected. The containment
+ * check runs on the normalised value, which is the one that is stored and
+ * later resolved, so a prefix that normalisation removes cannot smuggle a
+ * drive or absolute form past it (`./C:x` and `a/../C:x` store `C:x`,
+ * `docs/../C:/x` stores `C:/x`; all rejected). It also runs on the value as
+ * written, so an absolute or drive path is never silently reinterpreted as
+ * a relative one (`C:/../docs` would normalise to `docs`). An accepted
+ * value's stored form is therefore accepted again unchanged. `.` (the
+ * worktree top level itself) is accepted only when `allowTop` is set, which
+ * is the case for `repoRoot` and not for `path`. The backslash rule is
+ * platform-independent: POSIX normalisation treats `\` as an ordinary
+ * character, so `..\outside` would pass the `..` test here and still resolve
+ * outside the worktree under Windows path semantics; the stored separator
+ * is always `/`.
+ */
+function normalizeKnowledgePathField(value, allowTop) {
+    if (typeof value !== "string")
+        return { reason: "is not a string" };
+    if (value === "")
+        return { reason: "is empty" };
+    if (value.includes("\\"))
+        return { reason: "contains a backslash" };
+    let normalized = posix.normalize(value);
+    while (normalized.length > 1 && normalized.endsWith("/")) {
+        normalized = normalized.slice(0, -1);
+    }
+    const problem = knowledgePathContainmentProblem(value) ??
+        knowledgePathContainmentProblem(normalized);
+    if (problem !== undefined)
+        return { reason: problem };
+    if (normalized === "." && !allowTop) {
+        return { reason: "names the worktree top level itself" };
+    }
+    return { value: normalized };
+}
+/**
+ * Checks one raw `knowledge` entry. `path` (the bundle directory) and
+ * `repoRoot` (the root of the repository its sources live in) are each
+ * resolved against the worktree top level, independently of one another, so
+ * a workspace-level bundle whose sources live in a sub-repo is
+ * `{ path: "docs/okf", repoRoot: "sub" }`. `repoRoot` defaults to `"."`
+ * when omitted. Returns the normalised entry, or the reason it is invalid
+ * (naming the offending field) for the caller to throw or report.
+ */
+export function checkKnowledgeEntry(entry) {
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+        return { reason: "is not an object" };
+    }
+    const candidate = entry;
+    const path = normalizeKnowledgePathField(candidate.path, false);
+    if ("reason" in path)
+        return { reason: `path ${path.reason}` };
+    const repoRoot = normalizeKnowledgePathField(candidate.repoRoot === undefined ? "." : candidate.repoRoot, true);
+    if ("reason" in repoRoot)
+        return { reason: `repoRoot ${repoRoot.reason}` };
+    return { bundle: { path: path.value, repoRoot: repoRoot.value } };
+}
+/**
+ * Lists every problem in a raw on-disk `knowledge` value: `[]` when the
+ * field is absent or every entry is valid, one item for a non-array value,
+ * otherwise one item per invalid entry with its index and reason. `doctor`
+ * reports these, since {@link parseKnowledgeBundles} drops such entries on
+ * read; `runInit` reports them as notes when a re-install that carries
+ * `knowledge` forward rewrites the manifest and so removes them from disk.
+ */
+export function knowledgeEntryProblems(raw) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw)) {
+        return ["knowledge is not an array and is ignored"];
+    }
+    const problems = [];
+    raw.forEach((entry, index) => {
+        const checked = checkKnowledgeEntry(entry);
+        if ("reason" in checked) {
+            problems.push(`knowledge[${index}] ${checked.reason} and is ignored`);
+        }
+    });
+    return problems;
+}
+/**
+ * Validates an explicitly-supplied `options.knowledge` array for `runInit`
+ * with {@link checkKnowledgeEntry} and returns the normalised entries.
+ * Throws on the first invalid entry -- explicit input refuses to write a
+ * malformed record rather than dropping it (contrast
+ * {@link parseKnowledgeBundles}, which degrades a hand-edited/damaged
+ * on-disk manifest by dropping bad entries instead of throwing).
+ */
+export function validateKnowledgeBundles(knowledge) {
+    if (!Array.isArray(knowledge)) {
+        throw new Error("options.knowledge must be an array of { path, repoRoot } entries");
+    }
+    return knowledge.map((entry, index) => {
+        const checked = checkKnowledgeEntry(entry);
+        if ("reason" in checked) {
+            throw new Error(`options.knowledge[${index}] ${checked.reason}; path and repoRoot must be relative paths inside the worktree top level`);
+        }
+        return checked.bundle;
+    });
+}
+/**
+ * Sanitizes a possibly hand-edited or damaged on-disk manifest's raw
+ * `knowledge` field for {@link readInstalledManifest}: an entry that fails
+ * {@link checkKnowledgeEntry} is dropped rather than throwing (the read path
+ * can never crash a re-install on tampered input, the same reasoning
+ * `files`/`models` already document above), and a valid entry is kept in
+ * its normalised spelling. Returns `undefined` when the raw field is absent
+ * or not an array, so the "never configured" and "configured but empty"
+ * states stay distinct the same way `routing`'s own `"routing" in
+ * candidate` check does.
+ */
+function parseKnowledgeBundles(candidate) {
+    if (!("knowledge" in candidate) || !Array.isArray(candidate.knowledge)) {
+        return undefined;
+    }
+    const result = [];
+    for (const entry of candidate.knowledge) {
+        const checked = checkKnowledgeEntry(entry);
+        if ("bundle" in checked)
+            result.push(checked.bundle);
+    }
+    return result;
+}
 /**
  * Reads the manifest of a previous install, if any. Manifests can be written
  * by hand (manual agent installs) or damaged, so every field is sanitized;
@@ -102,6 +251,8 @@ export function readInstalledManifest(targetDir) {
     if ("routing" in candidate) {
         routing = parseRouting(candidate.routing);
     }
+    const knowledge = parseKnowledgeBundles(candidate);
+    const knowledgeProblems = knowledgeEntryProblems(candidate.knowledge);
     // A hand-written or damaged manifest may carry a non-string `pin`; that
     // degrades to "no recorded pin" here (the same per-field-degradation
     // style as `profile`/`tiers` above) rather than throwing. An empty or
@@ -117,6 +268,8 @@ export function readInstalledManifest(targetDir) {
         profile,
         tiers,
         ...(routing !== undefined ? { routing } : {}),
+        ...(knowledge !== undefined ? { knowledge } : {}),
+        ...(knowledgeProblems.length > 0 ? { knowledgeProblems } : {}),
         ...opencodeMaps,
         files,
         installedAt: typeof candidate.installedAt === "string" ? candidate.installedAt : "",
@@ -348,6 +501,14 @@ export function runInit(options) {
         updateOpencodeModels: options.opencodeModels !== undefined,
         updateOpencodeClassModels: options.opencodeClassModels !== undefined,
     });
+    // `undefined` carries the previous manifest's `knowledge` forward
+    // unchanged, the same omitted-means-sticky convention `routing`/`pin` use
+    // above; a present array (including `[]`) is validated and replaces the
+    // previous value outright, throwing before any file is written on an
+    // invalid entry rather than persisting a malformed record.
+    const knowledge = options.knowledge !== undefined
+        ? validateKnowledgeBundles(options.knowledge)
+        : previous?.knowledge;
     // Check only rendered selections before the first mutation.
     for (const warning of codexCatalogWarnings(routing, { harnesses: options.harnesses, profile, tiers }, options.codexCatalog)) {
         report.notes.push(`Codex catalog: ${warning}`);
@@ -677,6 +838,7 @@ export function runInit(options) {
         profile,
         tiers,
         routing,
+        ...(knowledge !== undefined ? { knowledge } : {}),
         ...compatibility,
         files: installedFiles,
         ...(pin !== undefined ? { pin } : {}),
@@ -691,6 +853,9 @@ export function runInit(options) {
             profile: previous.profile,
             tiers: previous.tiers,
             ...(previous.routing !== undefined ? { routing: previous.routing } : {}),
+            ...(previous.knowledge !== undefined
+                ? { knowledge: previous.knowledge }
+                : {}),
             ...legacyOpencodeFallbacks(previous),
             files: previous.files,
             ...(previous.pin !== undefined ? { pin: previous.pin } : {}),
@@ -698,6 +863,16 @@ export function runInit(options) {
         report.skipped.push(manifestPath);
     }
     else {
+        // `previous.knowledge` was sanitized on read, so rewriting the manifest
+        // from it removes each invalid hand-edited entry (or a non-array value)
+        // from disk, after which `doctor` has nothing left to report. Name each
+        // one here instead. An explicit `options.knowledge` replaces the whole
+        // field on purpose and gets no note.
+        if (options.knowledge === undefined) {
+            for (const problem of previous?.knowledgeProblems ?? []) {
+                report.notes.push(`manifest: ${problem}; dropped from the rewritten manifest`);
+            }
+        }
         const manifest = {
             ...desired,
             installedAt: previous?.installedAt || new Date().toISOString(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orchestrator-workflow",
-  "version": "0.40.1",
+  "version": "0.42.0",
   "description": "Installer for an orchestrator-led agent workflow: .ai/ run state, an AGENTS.md policy section, and per-harness subagent definitions for Claude Code, OpenAI Codex, and opencode",
   "main": "dist/index.js",
   "type": "module",