@deftai/directive-core 0.55.0

package/dist/content-contracts/standards/_helpers.js

@@ -0,0 +1,227 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+/** Repo root (deft framework checkout). */
+export function repoRoot() {
+    const here = fileURLToPath(new URL(".", import.meta.url));
+    return resolve(here, "../../../../../");
+}
+/**
+ * Resolve a repo-root-relative content path across both contexts (#1875 C1).
+ *
+ * The content/ move relocated every shippable asset under a single content/
+ * root in the SOURCE repo; the C1 flatten strips that prefix in a CONSUMER
+ * deposit. These content-contract tests address content by its consumer-relative
+ * path (e.g. `coding/coding.md`, `strategies/README.md`). Probe content/ first
+ * so the SOURCE layout resolves, then fall back to the repo root so root-resident
+ * entries (harness-entry main.md/AGENTS.md, repo-dev tests/, README.md, etc.)
+ * and the flattened consumer layout both still resolve. Mirrors
+ * scripts/_content_root.py + content-root.ts::contentRoot.
+ */
+export function resolveContentPath(relPath) {
+    const root = repoRoot();
+    const underContent = join(root, "content", relPath);
+    if (existsSync(underContent)) {
+        return underContent;
+    }
+    return join(root, relPath);
+}
+export function readText(relPath) {
+    return readFileSync(resolveContentPath(relPath), { encoding: "utf8" });
+}
+export function readAbs(absPath) {
+    return readFileSync(absPath, { encoding: "utf8" });
+}
+export function pathExists(relPath) {
+    return existsSync(resolveContentPath(relPath));
+}
+export function loadKnownFailures() {
+    const raw = readText("tests/content/snapshots/known_failures.json");
+    return JSON.parse(raw).known_failures;
+}
+export function xfailFiles(check) {
+    return new Set(loadKnownFailures()
+        .filter((e) => e.xfail && e.check === check && e.file)
+        .map((e) => e.file));
+}
+export function exemptFiles(check) {
+    return new Set(loadKnownFailures()
+        .filter((e) => e.exempt && e.check === check && e.file)
+        .map((e) => e.file));
+}
+export function xfailComposite(check) {
+    return new Set(loadKnownFailures()
+        .filter((e) => e.xfail && e.check === check && e.composite_key)
+        .map((e) => e.composite_key));
+}
+const SKIP_DIRS = new Set([
+    ".git",
+    ".venv",
+    "__pycache__",
+    ".pytest_cache",
+    "backup",
+    "dist",
+    "tests",
+    ".deft-cache",
+]);
+const MIGRATION_ARTIFACT_TREES = ["vbrief/migration"];
+export function isMigrationArtifact(rel) {
+    if (MIGRATION_ARTIFACT_TREES.some((t) => rel.startsWith(`${t}/`))) {
+        return true;
+    }
+    const name = rel.split("/").pop() ?? rel;
+    return name.includes(".premigrate.");
+}
+/** All .md paths relative to repo root. */
+export function allMdFiles(excludeTrees = []) {
+    const root = repoRoot();
+    const result = [];
+    function walk(dir) {
+        for (const ent of readdirSync(dir, { withFileTypes: true })) {
+            if (SKIP_DIRS.has(ent.name)) {
+                continue;
+            }
+            const abs = join(dir, ent.name);
+            if (ent.isDirectory()) {
+                walk(abs);
+                continue;
+            }
+            if (!ent.name.endsWith(".md")) {
+                continue;
+            }
+            const rel = relative(root, abs).split("\\").join("/");
+            if (excludeTrees.some((t) => rel.startsWith(`${t}/`))) {
+                continue;
+            }
+            if (isMigrationArtifact(rel)) {
+                continue;
+            }
+            result.push(rel);
+        }
+    }
+    walk(root);
+    return result.sort();
+}
+export function mdFilesInDir(dirname) {
+    const dir = resolveContentPath(dirname);
+    if (!existsSync(dir)) {
+        return [];
+    }
+    return readdirSync(dir)
+        .filter((f) => f.endsWith(".md"))
+        .map((f) => `${dirname}/${f}`)
+        .sort();
+}
+export function contentAfterBanner(text) {
+    const lines = text.split("\n");
+    let i = 0;
+    if (i < lines.length && lines[i]?.startsWith("<!-- AUTO-GENERATED by task packs:render")) {
+        while (i < lines.length && (lines[i]?.trim().startsWith("<!--") ?? false)) {
+            i += 1;
+        }
+        while (i < lines.length && lines[i]?.trim() === "") {
+            i += 1;
+        }
+    }
+    return lines.slice(i).join("\n");
+}
+export function locateSection(text, heading) {
+    const anchored = `\n${heading}`;
+    const idx = text.indexOf(anchored);
+    if (idx < 0) {
+        throw new Error(`section heading ${JSON.stringify(heading)} not found at newline-anchored position`);
+    }
+    return idx + 1;
+}
+const LINK_RE = /\[[^\]]*\]\(([^)]+)\)/g;
+export function internalLinks(relPath) {
+    const filePath = resolveContentPath(relPath);
+    const text = readAbs(filePath);
+    const parent = dirname(filePath);
+    const results = [];
+    for (const m of text.matchAll(LINK_RE)) {
+        const target = m[1] ?? "";
+        if (target.startsWith("http://") ||
+            target.startsWith("https://") ||
+            target.startsWith("mailto:") ||
+            target.startsWith("#")) {
+            continue;
+        }
+        const pathPart = target.split("#")[0]?.trim() ?? "";
+        if (!pathPart) {
+            continue;
+        }
+        results.push({ target, resolved: resolve(parent, pathPart) });
+    }
+    return results;
+}
+export function seeAlsoLinks() {
+    const root = repoRoot();
+    const results = [];
+    for (const rel of allMdFiles()) {
+        const filePath = join(root, rel);
+        const text = readAbs(filePath);
+        for (const line of text.split("\n")) {
+            if (!line.toLowerCase().includes("see also")) {
+                continue;
+            }
+            for (const m of line.matchAll(LINK_RE)) {
+                const target = m[1] ?? "";
+                if (target.startsWith("http://") ||
+                    target.startsWith("https://") ||
+                    target.startsWith("mailto:") ||
+                    target.startsWith("#")) {
+                    continue;
+                }
+                const pathPart = target.split("#")[0]?.trim() ?? "";
+                if (!pathPart) {
+                    continue;
+                }
+                results.push({ source: rel, target, resolved: resolve(dirname(filePath), pathPart) });
+            }
+        }
+    }
+    return results.sort((a, b) => `${a.source}::${a.target}`.localeCompare(`${b.source}::${b.target}`));
+}
+export function parseStrategyFilenames() {
+    const readme = readText("strategies/README.md");
+    const seen = new Set();
+    const result = [];
+    for (const line of readme.split("\n")) {
+        const stripped = line.trim();
+        if (!stripped.startsWith("|")) {
+            continue;
+        }
+        const cells = stripped.split("|");
+        if (cells.length < 2) {
+            continue;
+        }
+        const firstCell = cells[1]?.trim() ?? "";
+        const match = firstCell.match(/\b([a-z][a-z0-9_-]*\.md)\b/);
+        if (match?.[1] && !seen.has(match[1])) {
+            seen.add(match[1]);
+            result.push(match[1]);
+        }
+    }
+    return result;
+}
+export function loadJson(relPath) {
+    return JSON.parse(readText(relPath));
+}
+export function isDir(relPath) {
+    try {
+        return statSync(resolveContentPath(relPath)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export function isFile(relPath) {
+    try {
+        return statSync(resolveContentPath(relPath)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=_helpers.js.map

package/dist/content-contracts/standards/_shapes.d.ts

@@ -0,0 +1,12 @@
+export interface ShapeSchema {
+    name: string;
+    requiredSections?: readonly string[];
+    oneOfSections?: readonly string[];
+    minH2Count?: number;
+}
+export declare const LANGUAGE_SHAPE: ShapeSchema;
+export declare const STRATEGY_SHAPE: ShapeSchema;
+export declare const INTERFACE_SHAPE: ShapeSchema;
+export declare const TOOL_SHAPE: ShapeSchema;
+export declare function validateShape(text: string, schema: ShapeSchema): string[];
+//# sourceMappingURL=_shapes.d.ts.map

package/dist/content-contracts/standards/_shapes.js

@@ -0,0 +1,45 @@
+export const LANGUAGE_SHAPE = {
+    name: "language",
+    requiredSections: ["Standards", "Commands", "Patterns"],
+};
+export const STRATEGY_SHAPE = {
+    name: "strategy",
+    requiredSections: ["When to Use", "Workflow"],
+};
+export const INTERFACE_SHAPE = {
+    name: "interface",
+    oneOfSections: ["Core Architecture", "Framework Selection"],
+};
+export const TOOL_SHAPE = {
+    name: "tool",
+    minH2Count: 1,
+};
+const H2_RE = /^##\s+(.+)$/gm;
+export function validateShape(text, schema) {
+    const headers = [];
+    for (const m of text.matchAll(H2_RE)) {
+        if (m[1]) {
+            headers.push(m[1]);
+        }
+    }
+    const headersLower = headers.map((h) => h.toLowerCase());
+    const violations = [];
+    for (const section of schema.requiredSections ?? []) {
+        if (!headersLower.some((h) => h.includes(section.toLowerCase()))) {
+            violations.push(`missing required section '## ${section}'`);
+        }
+    }
+    if (schema.oneOfSections?.length) {
+        const hit = schema.oneOfSections.some((s) => headersLower.some((h) => h.includes(s.toLowerCase())));
+        if (!hit) {
+            const options = schema.oneOfSections.map((s) => `'## ${s}'`).join(" or ");
+            violations.push(`missing at least one of: ${options}`);
+        }
+    }
+    const min = schema.minH2Count ?? 0;
+    if (min > 0 && headers.length < min) {
+        violations.push(`needs at least ${min} '##' section(s), found ${headers.length}`);
+    }
+    return violations;
+}
+//# sourceMappingURL=_shapes.js.map

package/dist/content-contracts/standards/_taskfile-helpers.d.ts

@@ -0,0 +1,12 @@
+export declare function taskYamlFiles(): string[];
+export declare function iterTaskBlocks(text: string): Array<{
+    name: string;
+    start: number;
+    end: number;
+}>;
+export declare function blockBody(text: string, start: number, end: number): string;
+export declare function nonCommentLines(block: string): string[];
+export declare function cachingKeyOnLine(line: string): string | null;
+export declare function readTaskfile(name: string): string;
+export declare function readRoot(name: string): string;
+//# sourceMappingURL=_taskfile-helpers.d.ts.map

package/dist/content-contracts/standards/_taskfile-helpers.js

@@ -0,0 +1,61 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { repoRoot } from "./_helpers.js";
+const TASK_HEADER = /^ {2}([A-Za-z_][\w:-]*)\s*:\s*(?:#.*)?$/;
+const CACHING_KEY = /^ {4}(sources|generates)\s*:\s*(?:#.*)?$/;
+export function taskYamlFiles() {
+    const dir = join(repoRoot(), "tasks");
+    return readdirSync(dir)
+        .filter((f) => f.endsWith(".yml") || f.endsWith(".yaml"))
+        .map((f) => join(dir, f))
+        .sort();
+}
+export function iterTaskBlocks(text) {
+    const lines = text.split("\n");
+    const taskPositions = [];
+    let inTasksSection = false;
+    for (let idx = 0; idx < lines.length; idx += 1) {
+        const line = lines[idx] ?? "";
+        if (line.startsWith("tasks:")) {
+            inTasksSection = true;
+            continue;
+        }
+        if (inTasksSection && line && !line.startsWith(" ") && line.trim() !== "tasks:") {
+            inTasksSection = false;
+        }
+        if (!inTasksSection) {
+            continue;
+        }
+        const m = line.match(TASK_HEADER);
+        if (m?.[1]) {
+            taskPositions.push({ name: m[1], start: idx });
+        }
+    }
+    const blocks = [];
+    for (let i = 0; i < taskPositions.length; i += 1) {
+        const cur = taskPositions[i];
+        const next = taskPositions[i + 1];
+        if (!cur) {
+            continue;
+        }
+        blocks.push({ name: cur.name, start: cur.start, end: next?.start ?? lines.length });
+    }
+    return blocks;
+}
+export function blockBody(text, start, end) {
+    return text.split("\n").slice(start, end).join("\n");
+}
+export function nonCommentLines(block) {
+    return block.split("\n").filter((ln) => !ln.trimStart().startsWith("#"));
+}
+export function cachingKeyOnLine(line) {
+    const m = line.match(CACHING_KEY);
+    return m?.[1] ?? null;
+}
+export function readTaskfile(name) {
+    return readFileSync(join(repoRoot(), "tasks", name), { encoding: "utf8" });
+}
+export function readRoot(name) {
+    return readFileSync(join(repoRoot(), "tasks", "..", name), { encoding: "utf8" });
+}
+//# sourceMappingURL=_taskfile-helpers.js.map

package/dist/content-root.d.ts

@@ -0,0 +1,47 @@
+/**
+ * content-root.ts -- resolve the shippable-content root across both contexts.
+ *
+ * The #1875 "content/ move" relocated every shippable framework asset under a
+ * single `content/` root in the SOURCE repo. The C1 flatten deposit strips that
+ * prefix when packaging, so a CONSUMER install sees the same `.deft/core/<x>`
+ * layout it always had -- there is no `content/` directory in a deposited
+ * framework.
+ *
+ * Engine modules that read shippable content by framework-root path (the event
+ * registry, content packs, vBRIEF schemas, skill bodies, ...) therefore live in
+ * two worlds:
+ *
+ *   - SOURCE checkout:  content lives at `<framework-root>/content/<x>`.
+ *   - CONSUMER deposit: content lives at `<framework-root>/<x>` (flattened).
+ *
+ * `contentRoot(frameworkRoot)` resolves the difference by probing for the
+ * `content/` directory: it returns `<framework-root>/content` when that
+ * directory exists (source) and `<framework-root>` otherwise (consumer). Build
+ * content paths off the returned root so the same code resolves both contexts
+ * without a branch. Mirrors scripts/_content_root.py::content_root.
+ *
+ * #11 / C4 adds a third source: when `@deftai/directive-content` is installed
+ * in `node_modules`, the resolver prefers that package root (already flattened)
+ * and falls back to the vendored `.deft/core/` deposit / in-repo `content/`
+ * layout across in-repo-vendored, hybrid npm-engine, and external-workspace
+ * operating modes.
+ *
+ * Refs #1875 (content/ move), #1669 (Wave-1 LockedDecisions C1 flatten), #11.
+ */
+export declare const CONTENT_DIRNAME = "content";
+export declare const CONTENT_PACKAGE_NAME = "@deftai/directive-content";
+/**
+ * Walk upward from `searchFrom` and return the installed content package root.
+ *
+ * Termination uses the idempotent-`dirname` pattern: `dirname` returns its own
+ * input at the filesystem root on BOTH POSIX (`/` -> `/`) and Windows (`C:\` ->
+ * `C:\`, `\\\\share` -> `\\\\share`), so `parent === dir` is the portable
+ * stop condition. A hardcoded `resolve("/")` comparison is NOT safe on Windows:
+ * `resolve("/")` yields the drive root of the CWD, which never equals the walk
+ * cursor when `searchFrom` is on a different drive (or a UNC path) -- the
+ * classic Windows drive-root infinite loop. A max-depth guard backstops both.
+ */
+export declare function resolveContentPackageRoot(searchFrom: string): string | null;
+/** Return the directory that holds flattened shippable content. */
+export declare function contentRoot(frameworkRoot: string): string;
+//# sourceMappingURL=content-root.d.ts.map

package/dist/content-root.js

@@ -0,0 +1,89 @@
+/**
+ * content-root.ts -- resolve the shippable-content root across both contexts.
+ *
+ * The #1875 "content/ move" relocated every shippable framework asset under a
+ * single `content/` root in the SOURCE repo. The C1 flatten deposit strips that
+ * prefix when packaging, so a CONSUMER install sees the same `.deft/core/<x>`
+ * layout it always had -- there is no `content/` directory in a deposited
+ * framework.
+ *
+ * Engine modules that read shippable content by framework-root path (the event
+ * registry, content packs, vBRIEF schemas, skill bodies, ...) therefore live in
+ * two worlds:
+ *
+ *   - SOURCE checkout:  content lives at `<framework-root>/content/<x>`.
+ *   - CONSUMER deposit: content lives at `<framework-root>/<x>` (flattened).
+ *
+ * `contentRoot(frameworkRoot)` resolves the difference by probing for the
+ * `content/` directory: it returns `<framework-root>/content` when that
+ * directory exists (source) and `<framework-root>` otherwise (consumer). Build
+ * content paths off the returned root so the same code resolves both contexts
+ * without a branch. Mirrors scripts/_content_root.py::content_root.
+ *
+ * #11 / C4 adds a third source: when `@deftai/directive-content` is installed
+ * in `node_modules`, the resolver prefers that package root (already flattened)
+ * and falls back to the vendored `.deft/core/` deposit / in-repo `content/`
+ * layout across in-repo-vendored, hybrid npm-engine, and external-workspace
+ * operating modes.
+ *
+ * Refs #1875 (content/ move), #1669 (Wave-1 LockedDecisions C1 flatten), #11.
+ */
+import { statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+export const CONTENT_DIRNAME = "content";
+export const CONTENT_PACKAGE_NAME = "@deftai/directive-content";
+/**
+ * Defensive upper bound on the ancestor walk. A correctly-terminating walk
+ * stops at the filesystem root in far fewer than this many steps on every
+ * platform; the cap exists only so a future regression in the root-detection
+ * logic degrades to "not found" instead of hanging the process. 256 dwarfs any
+ * realistic absolute-path depth.
+ */
+const MAX_ANCESTOR_WALK_DEPTH = 256;
+/**
+ * Walk upward from `searchFrom` and return the installed content package root.
+ *
+ * Termination uses the idempotent-`dirname` pattern: `dirname` returns its own
+ * input at the filesystem root on BOTH POSIX (`/` -> `/`) and Windows (`C:\` ->
+ * `C:\`, `\\\\share` -> `\\\\share`), so `parent === dir` is the portable
+ * stop condition. A hardcoded `resolve("/")` comparison is NOT safe on Windows:
+ * `resolve("/")` yields the drive root of the CWD, which never equals the walk
+ * cursor when `searchFrom` is on a different drive (or a UNC path) -- the
+ * classic Windows drive-root infinite loop. A max-depth guard backstops both.
+ */
+export function resolveContentPackageRoot(searchFrom) {
+    let dir = resolve(searchFrom);
+    for (let depth = 0; depth < MAX_ANCESTOR_WALK_DEPTH; depth += 1) {
+        const pkgJson = join(dir, "node_modules", "@deftai", "directive-content", "package.json");
+        try {
+            if (statSync(pkgJson).isFile()) {
+                return dirname(pkgJson);
+            }
+        }
+        catch {
+            // No physical install at this ancestor -- keep walking.
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+/** Return the directory that holds flattened shippable content. */
+export function contentRoot(frameworkRoot) {
+    const packageRoot = resolveContentPackageRoot(frameworkRoot);
+    if (packageRoot)
+        return packageRoot;
+    const candidate = join(frameworkRoot, CONTENT_DIRNAME);
+    try {
+        if (statSync(candidate).isDirectory()) {
+            return candidate;
+        }
+    }
+    catch {
+        // No content/ dir -> consumer (flattened) deposit; fall through.
+    }
+    return frameworkRoot;
+}
+//# sourceMappingURL=content-root.js.map

package/dist/doctor/agents-md.d.ts

@@ -0,0 +1,14 @@
+export interface AgentsMdSeams {
+    readonly frameworkRoot?: string;
+    readonly readTemplate?: () => string | null;
+    readonly resolveSha?: () => string;
+    readonly nowIso?: () => string;
+    readonly newSession?: () => string;
+    readonly readAgents?: (path: string) => string | null;
+}
+/** Compute AGENTS.md managed-section freshness plan (mirrors scripts/_agents_md.py). */
+export declare function agentsRefreshPlan(projectRoot: string, seams?: AgentsMdSeams): Record<string, unknown>;
+export declare function hasV3ManagedMarker(projectRoot: string, readText?: typeof defaultReadAgents): boolean;
+declare function defaultReadAgents(path: string): string | null;
+export {};
+//# sourceMappingURL=agents-md.d.ts.map