@deftai/directive-core 0.87.0 → 0.89.0

package/dist/init-deposit/scaffold.js

@@ -5,11 +5,12 @@
  * Refs #1942, #1430, #1463, #1179.
  */
 import { execFileSync } from "node:child_process";
-import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync, } from "node:fs";
-import { mkdir, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { mkdir, readdir, rm, stat } from "node:fs/promises";
 import { platform } from "node:os";
-import { dirname, join, relative } from "node:path";
-import { assertProjectionContained, ProjectionContainmentError, } from "../fs/projection-containment.js";
+import { join, relative, resolve } from "node:path";
+import { containedWrite } from "../fs/contained-write.js";
+import { assertDestinationNotSymlink, ProjectionContainmentError, } from "../fs/projection-containment.js";
 import { agentsRefreshPlan } from "../platform/agents-md.js";
 import { MIGRATED_ARTIFACT_DIR } from "../xbrief-migrate/constants.js";
 import { CANONICAL_INSTALL_ROOT } from "./constants.js";
@@ -17,12 +18,29 @@ import { installerManagedGuardEre } from "./hygiene.js";
 import { syncConsumerXbriefSchemas } from "./xbrief-projections.js";
 export { CANONICAL_INSTALL_ROOT };
 export const CORE_GLOB = ".deft/core/**";
-/** Refuse init/update projection writes that escape via repo-controlled symlinks (#2446). */
+/**
+ * Refuse init/update projection writes that escape via repo-controlled symlinks
+ * (#2446) OR that would follow an in-tree destination symlink on the write path
+ * (#2912). Every consumer projection sink in this module routes through here.
+ */
 function projectionTarget(projectDir, ...relSegments) {
     const target = join(projectDir, ...relSegments);
-    assertProjectionContained(projectDir, target);
+    assertDestinationNotSymlink(projectDir, target);
     return target;
 }
+/**
+ * Product write sink: containment root is the project, then containedWrite
+ * (#2951 / #2980 wave A). Call after projectionTarget / assertDestinationNotSymlink
+ * when the early ProjectionContainmentError type is required by tests.
+ */
+function containedProjectWrite(projectDir, target, data) {
+    containedWrite({
+        root: resolve(projectDir),
+        target,
+        data,
+        mode: "replace",
+    });
+}
 const CODEQL_CONFIG_REL = ".github/codeql/codeql-config.yml";
 const CORE_GUARD_WORKFLOW_REL = ".github/workflows/deft-core-guard.yml";
 const FRAMEWORK_SELF_TEST_REL = ".deft/core/tests";
@@ -215,9 +233,9 @@ export function writeInstallManifest(projectDir, deftDir, fields) {
         relative(projectDir, deftDir).split("\\").join("/") ||
         CANONICAL_INSTALL_ROOT;
     const body = buildInstallManifestText({ ...fields, installRoot });
-    mkdirSync(deftDir, { recursive: true });
     const path = join(deftDir, "VERSION");
-    writeFileSync(path, body, "utf8");
+    // #2980 wave A: product write sink routes through containedWrite.
+    containedProjectWrite(projectDir, path, body);
     return path;
 }
 /** Canonical committed pin dependency name (mirrors resolution/pin.ts). */
@@ -271,7 +289,7 @@ export function ensurePackageJsonPin(projectDir, version, io) {
     }
     devDeps[PIN_DEPENDENCY_NAME] = pinVersion;
     pkg.devDependencies = devDeps;
-    writeFileSync(path, `${JSON.stringify(pkg, null, 2)}\n`, "utf8");
+    containedProjectWrite(projectDir, path, `${JSON.stringify(pkg, null, 2)}\n`);
     io.printf(existed
         ? `package.json updated: pinned ${PIN_DEPENDENCY_NAME}@${pinVersion} (exact).\n`
         : `package.json created: pinned ${PIN_DEPENDENCY_NAME}@${pinVersion} (exact, private).\n`);
@@ -292,7 +310,7 @@ export function writeAgentsMd(projectDir, deftDir, io) {
         throw new Error("AGENTS.md render produced no content");
     }
     const path = projectionTarget(projectDir, "AGENTS.md");
-    writeFileSync(path, newContent, "utf8");
+    containedProjectWrite(projectDir, path, newContent);
     if (state === "absent") {
         io.printf("AGENTS.md created.\n");
     }
@@ -316,7 +334,7 @@ async function ensureVbriefLifecycleDirs(projectDir) {
         const entries = await readdir(dir);
         if (entries.length > 0)
             continue;
-        await writeFile(gitkeep, VBRIEF_LIFECYCLE_GITKEEP, "utf8");
+        containedProjectWrite(projectDir, gitkeep, VBRIEF_LIFECYCLE_GITKEEP);
     }
 }
 function vbriefLifecycleDirsPresent(consumerVbrief) {
@@ -350,7 +368,7 @@ export async function writeConsumerVbrief(projectDir, deftDir, io) {
             copyFileSync(fwVbriefMd, vbriefMdDst);
         }
         else {
-            writeFileSync(vbriefMdDst, VBRIEF_README_BODY, "utf8");
+            containedProjectWrite(projectDir, vbriefMdDst, VBRIEF_README_BODY);
         }
     }
     await ensureVbriefLifecycleDirs(projectDir);
@@ -365,12 +383,10 @@ export function writeAgentsSkills(projectDir, io) {
         return false;
     }
     for (const skill of AGENTS_SKILLS) {
-        const dir = projectionTarget(projectDir, ".agents", "skills", skill.dir);
-        mkdirSync(dir, { recursive: true });
         const path = projectionTarget(projectDir, ".agents", "skills", skill.dir, "SKILL.md");
         if (existsSync(path))
             continue;
-        writeFileSync(path, skill.content, "utf8");
+        containedProjectWrite(projectDir, path, skill.content);
     }
     io.printf(".agents/skills/ created — deft skills will be auto-discovered.\n");
     return true;
@@ -455,21 +471,20 @@ export function ensureTaskfile(projectDir, io) {
                 "    optional: true\n";
         io.printf("Appended new `includes:` block with deft entry to Taskfile.yml (Epic-4).\n");
     }
-    writeFileSync(path, resultText, "utf8");
+    containedProjectWrite(projectDir, path, resultText);
     return true;
 }
 const HOOK_FILENAMES = ["pre-commit", "pre-push"];
 const HOOK_SUPPORT_FILENAMES = ["_deft-run.sh"];
 const HOOK_FILE_MODE = 0o755;
-const HOOK_SUPPORT_FILE_MODE = 0o644;
 export function writeConsumerGitHooks(projectDir, deftDir, io, seams = {}) {
     const srcDir = join(deftDir, ".githooks");
     if (!existsSync(srcDir) || !statSync(srcDir).isDirectory()) {
         io.printf(`git hooks source ${srcDir} absent — skipping hook wiring.\n`);
         return false;
     }
-    const dstDir = projectionTarget(projectDir, ".githooks");
-    mkdirSync(dstDir, { recursive: true });
+    // Ensure parent path is containment-checked before any file write.
+    projectionTarget(projectDir, ".githooks");
     let filesDeposited = false;
     for (const name of [...HOOK_FILENAMES, ...HOOK_SUPPORT_FILENAMES]) {
         const src = join(srcDir, name);
@@ -480,8 +495,8 @@ export function writeConsumerGitHooks(projectDir, deftDir, io, seams = {}) {
         const existing = existsSync(dst) ? readFileSync(dst) : null;
         const isHookScript = HOOK_FILENAMES.includes(name);
         if (!existing?.equals(data)) {
-            const mode = isHookScript ? HOOK_FILE_MODE : HOOK_SUPPORT_FILE_MODE;
-            writeFileSync(dst, data, { mode });
+            // #2980 wave A: containedWrite (mode is applied via chmod below for hooks).
+            containedProjectWrite(projectDir, dst, data);
             filesDeposited = true;
         }
         if (platform() !== "win32" && isHookScript) {
@@ -678,7 +693,7 @@ export function ensureGitattributes(projectDir, io) {
     for (const add of additions) {
         body += `${add}\n`;
     }
-    writeFileSync(path, body, "utf8");
+    containedProjectWrite(projectDir, path, body);
     io.printf(`.gitattributes updated with Deft core markers: ${additions.join(", ")}\n`);
     return true;
 }
@@ -721,7 +736,7 @@ export function ensureGreptileIgnore(projectDir, io) {
         return false;
     }
     obj.ignorePatterns = appendGreptilePattern(patterns, CORE_GLOB);
-    writeFileSync(path, `${JSON.stringify(obj, null, 2)}\n`, "utf8");
+    containedProjectWrite(projectDir, path, `${JSON.stringify(obj, null, 2)}\n`);
     io.printf(fileExisted
         ? `greptile.json updated: bot review now ignores ${CORE_GLOB}.\n`
         : `greptile.json created: bot review ignores ${CORE_GLOB}.\n`);
@@ -770,8 +785,7 @@ function insertCodeqlPathsIgnore(content, glob) {
 export function ensureCodeqlPathsIgnore(projectDir, io) {
     const path = projectionTarget(projectDir, CODEQL_CONFIG_REL);
     if (!existsSync(path)) {
-        mkdirSync(dirname(path), { recursive: true });
-        writeFileSync(path, codeqlConfigDefault(), "utf8");
+        containedProjectWrite(projectDir, path, codeqlConfigDefault());
         io.printf(`${CODEQL_CONFIG_REL} created: CodeQL ignores ${CORE_GLOB}.\n`);
         return true;
     }
@@ -784,7 +798,7 @@ export function ensureCodeqlPathsIgnore(projectDir, io) {
     const updated = inserted.ok
         ? inserted.content
         : `${existing}${existing.endsWith("\n") ? "" : "\n"}paths-ignore:\n  - '${CORE_GLOB}'\n`;
-    writeFileSync(path, updated, "utf8");
+    containedProjectWrite(projectDir, path, updated);
     io.printf(`${CODEQL_CONFIG_REL} updated: CodeQL now ignores ${CORE_GLOB}.\n`);
     return true;
 }
@@ -802,12 +816,11 @@ export function ensureCoreGuardWorkflow(projectDir, io) {
             io.printf(`${CORE_GUARD_WORKFLOW_REL} already current — skipping.\n`);
             return false;
         }
-        writeFileSync(path, refreshed, "utf8");
+        containedProjectWrite(projectDir, path, refreshed);
         io.printf(`${CORE_GUARD_WORKFLOW_REL} refreshed: deft-core-guard allowlist updated (#1478).\n`);
         return true;
     }
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, desired, "utf8");
+    containedProjectWrite(projectDir, path, desired);
     io.printf(`${CORE_GUARD_WORKFLOW_REL} created: CI refuses PRs mixing ${CORE_GLOB} with app files.\n`);
     return true;
 }

package/dist/init-deposit/xbrief-projections.js

@@ -5,9 +5,10 @@
  * freshness. A current `.deft/core/VERSION` therefore cannot short-circuit
  * these repairs.
  */
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
-import { join, relative } from "node:path";
-import { assertProjectionContained } from "../fs/projection-containment.js";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { containedWrite } from "../fs/contained-write.js";
+import { assertDestinationNotSymlink } from "../fs/projection-containment.js";
 import { resolveLifecycleRoot } from "../layout/resolve.js";
 import { DEV_FALLBACK } from "../platform/constants.js";
 import { MIGRATED_ARTIFACT_DIR } from "../xbrief-migrate/constants.js";
@@ -54,7 +55,7 @@ export function rewriteProjectedSchemaContent(content) {
  * Upstream vbrief/schemas/ may keep legacy paths; consumer copies must not (#2670).
  */
 export function assertProjectedSchemaDescriptionsRooted(projectDir, destinationDir) {
-    assertProjectionContained(projectDir, destinationDir);
+    assertDestinationNotSymlink(projectDir, destinationDir);
     if (!isDirectory(destinationDir))
         return;
     for (const rel of collectSchemaFiles(destinationDir)) {
@@ -66,7 +67,8 @@ export function assertProjectedSchemaDescriptionsRooted(projectDir, destinationD
     }
 }
 function writeFileIfChanged(projectDir, target, content) {
-    assertProjectionContained(projectDir, target);
+    // Keep early containment so ProjectionContainmentError type is preserved for callers/tests.
+    assertDestinationNotSymlink(projectDir, target);
     const desired = Buffer.isBuffer(content) ? content : Buffer.from(content, "utf8");
     try {
         if (readFileSync(target).equals(desired))
@@ -75,8 +77,13 @@ function writeFileIfChanged(projectDir, target, content) {
     catch {
         // Missing or unreadable target is replaced below.
     }
-    mkdirSync(join(target, ".."), { recursive: true });
-    writeFileSync(target, desired);
+    // #2980 wave A: product write sink routes through containedWrite.
+    containedWrite({
+        root: resolve(projectDir),
+        target,
+        data: desired,
+        mode: "replace",
+    });
     return true;
 }
 /**
@@ -91,7 +98,7 @@ export function syncConsumerXbriefSchemas(projectDir, deftDir) {
         throw new Error(`cannot project xbrief schemas: framework payload is missing ${CURRENT_CORE_SCHEMA}`);
     }
     const destinationDir = join(projectDir, MIGRATED_ARTIFACT_DIR, "schemas");
-    assertProjectionContained(projectDir, destinationDir);
+    assertDestinationNotSymlink(projectDir, destinationDir);
     mkdirSync(destinationDir, { recursive: true });
     let changed = false;
     for (const rel of collectSchemaFiles(sourceDir)) {
@@ -103,7 +110,7 @@ export function syncConsumerXbriefSchemas(projectDir, deftDir) {
         changed = writeFileIfChanged(projectDir, destination, projected) || changed;
     }
     const obsoleteDestination = join(destinationDir, OBSOLETE_CORE_SCHEMA);
-    assertProjectionContained(projectDir, obsoleteDestination);
+    assertDestinationNotSymlink(projectDir, obsoleteDestination);
     if (existsSync(obsoleteDestination)) {
         rmSync(obsoleteDestination, { force: true });
         changed = true;
@@ -117,7 +124,7 @@ function syncBareVersionMarkerWithPolicy(projectDir, version, allowRootFallback)
         return false;
     const canonicalRoot = join(projectDir, MIGRATED_ARTIFACT_DIR);
     if (existsSync(canonicalRoot)) {
-        assertProjectionContained(projectDir, join(canonicalRoot, ".deft-version"));
+        assertDestinationNotSymlink(projectDir, join(canonicalRoot, ".deft-version"));
     }
     let targetDir = projectDir;
     try {

package/dist/intake/candidates-log.js

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
-import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, unlinkSync, writeSync, } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import { ContainedWriteError, ContainedWriteErrorCode, containedWrite, } from "../fs/contained-write.js";
 import { pyRepr } from "../scm/py-format.js";
 import { resolveCandidatesLogPath } from "../triage/cache-path.js";
 function defaultLogPath() {
@@ -110,40 +111,45 @@ function validateEntry(entry) {
 function resolvePath(path) {
     return path !== undefined && path !== null ? resolve(path) : defaultLogPath();
 }
-function acquireAppendLock(logPath) {
+/**
+ * Cross-process exclusive lock via containedWrite mode=create (O_EXCL).
+ * #2980 wave B: lock + product appends route through containedWrite.
+ */
+function acquireAppendLock(logPath, containmentRoot) {
     while (threadLocked) {
         // spin-wait for in-process serialization
     }
     threadLocked = true;
-    const lockPath = join(dirname(logPath), `${logPath.split(/[/\\]/).pop()}.lock`);
+    const lockPath = resolve(dirname(logPath), `${basename(logPath)}.lock`);
     mkdirSync(dirname(lockPath), { recursive: true });
     const deadline = Date.now() + 30_000;
-    let fd = null;
-    while (fd === null) {
+    while (true) {
         try {
-            fd = openSync(lockPath, "wx");
-        }
-        catch {
-            if (Date.now() > deadline) {
-                threadLocked = false;
-                throw new CandidatesLogError("timed out acquiring candidates log lock");
-            }
-            const spinEnd = Date.now() + 20;
-            while (Date.now() < spinEnd) {
-                // brief spin
+            containedWrite({
+                root: containmentRoot,
+                target: lockPath,
+                data: "\0",
+                mode: "create",
+            });
+            break;
+        }
+        catch (err) {
+            if (err instanceof ContainedWriteError && err.code === ContainedWriteErrorCode.EXISTS) {
+                if (Date.now() > deadline) {
+                    threadLocked = false;
+                    throw new CandidatesLogError("timed out acquiring candidates log lock");
+                }
+                const spinEnd = Date.now() + 20;
+                while (Date.now() < spinEnd) {
+                    // brief spin
+                }
+                continue;
             }
+            threadLocked = false;
+            throw err;
         }
     }
-    writeSync(fd, Buffer.from("\0"));
     return () => {
-        try {
-            if (fd !== null) {
-                closeSync(fd);
-            }
-        }
-        catch {
-            // ignore
-        }
         try {
             unlinkSync(lockPath);
         }
@@ -153,24 +159,29 @@ function acquireAppendLock(logPath) {
         threadLocked = false;
     };
 }
+/** Ensure parent exists and return it as the containment root for log writes. */
+function containmentRootForLog(logPath) {
+    const parent = dirname(logPath);
+    mkdirSync(parent, { recursive: true });
+    return resolve(parent);
+}
 export function validateCandidatesEntry(entry) {
     validateEntry(entry);
 }
 export function append(entry, options = {}) {
     validateEntry(entry);
     const logPath = resolvePath(options.path);
-    mkdirSync(dirname(logPath), { recursive: true });
+    const root = containmentRootForLog(logPath);
     const line = JSON.stringify(entry, Object.keys(entry).sort());
-    const release = acquireAppendLock(logPath);
+    const release = acquireAppendLock(logPath, root);
     try {
-        const fd = openSync(logPath, "a");
-        try {
-            writeSync(fd, Buffer.from(`${line}\n`, "utf8"));
-            fsyncSync(fd);
-        }
-        finally {
-            closeSync(fd);
-        }
+        // #2980 wave B: product write sink routes through containedWrite.
+        containedWrite({
+            root,
+            target: logPath,
+            data: `${line}\n`,
+            mode: "append",
+        });
     }
     finally {
         release();

package/dist/intake/github-body-cli.d.ts

@@ -1,3 +1,9 @@
 #!/usr/bin/env node
+/**
+ * Production entry for `task scm:body:*` / `directive github-body <subcommand>`.
+ * Dispatch peels the `github-body` verb; argv[0] is the subcommand
+ * (`issue-lint`, `pr-lint`, `issue-edit`, …). Wired through githubBodyMain
+ * so create/edit fail closed and lint commands share one encoding gate (#2960).
+ */
 export declare function mainEntry(argv?: string[]): number;
 //# sourceMappingURL=github-body-cli.d.ts.map

package/dist/intake/github-body-cli.js

@@ -19,9 +19,26 @@ function parseArgs(argv) {
             out.bodyFile = argv[++i];
         else if (arg === "--out-file")
             out.outFile = argv[++i];
+        else if (/^\d+$/.test(arg)) {
+            // Positional number: issue-lint / issue-* use --issue; pr-lint / pr-* use --pr (#2960).
+            const n = Number.parseInt(arg, 10);
+            if (out.command.startsWith("pr-")) {
+                if (out.pr === undefined)
+                    out.pr = n;
+            }
+            else if (out.issue === undefined) {
+                out.issue = n;
+            }
+        }
     }
     return out;
 }
+/**
+ * Production entry for `task scm:body:*` / `directive github-body <subcommand>`.
+ * Dispatch peels the `github-body` verb; argv[0] is the subcommand
+ * (`issue-lint`, `pr-lint`, `issue-edit`, …). Wired through githubBodyMain
+ * so create/edit fail closed and lint commands share one encoding gate (#2960).
+ */
 export function mainEntry(argv = process.argv.slice(2)) {
     const parsed = parseArgs(argv);
     return githubBodyMain(parsed);

package/dist/intake/github-body.d.ts

@@ -1,6 +1,12 @@
+import { type Finding } from "../encoding/scan.js";
 export declare const DEFAULT_TIMEOUT_SECONDS = 60;
+/** Stable error code for CP1252/CP437-as-UTF-8 / U+FFFD body corruption (#2960). */
+export declare const SCM_BODY_ENCODING_CODE = "scm-body-encoding";
 export declare class GitHubBodyError extends Error {
-    constructor(message: string);
+    readonly code?: string;
+    constructor(message: string, options?: {
+        code?: string;
+    });
 }
 export type RunGhApiFn = (args: readonly string[], options?: {
     inputText?: string | null;
@@ -9,7 +15,22 @@ export type RunGhApiFn = (args: readonly string[], options?: {
 /** Resolve the live GitHub CLI used for writes and mutation read-back. */
 export declare function resolveLiveGh(): string;
 export declare function readBody(bodyFile: string, stdinText?: string | null): string;
-/** Fail closed when live read-back body is flattened or mojibaked vs intended payload (#2607). */
+/** Strip a leading UTF-8 BOM so body-file writers stay UTF-8 no BOM (#2960 / #798). */
+export declare function stripUtf8Bom(text: string): string;
+/**
+ * Scan body text with the same mojibake pattern set as verify:encoding
+ * (`packages/core/src/encoding/patterns.ts` / scanLine). Issue/PR bodies are
+ * Markdown: strip fenced blocks and inline code spans so documented examples
+ * of the corruption class (e.g. `#2960` fixtures) are not false positives —
+ * matches `scanFile` .md behavior.
+ */
+export declare function scanBodyText(body: string, source?: string): Finding[];
+/**
+ * Fail closed when body text already contains CP1252/CP437-as-UTF-8 mojibake
+ * or U+FFFD (before PATCH and as a live-body diagnostic).
+ */
+export declare function assertBodyEncoding(body: string, phase: string): void;
+/** Fail closed when live read-back body is flattened or mojibaked vs intended payload (#2607 / #2960). */
 export declare function verifyBodyPostcondition(intended: string, live: string): void;
 export declare function createIssue(repo: string, options: {
     title: string;
@@ -41,10 +62,29 @@ export declare function fetchIssueBody(repo: string, issue: number, options?: {
     binary?: string | null;
     runFn?: RunGhApiFn;
 }): string;
+export declare function fetchPrBody(repo: string, pr: number, options?: {
+    binary?: string | null;
+    runFn?: RunGhApiFn;
+}): string;
 export declare function writeIssueBodyToFile(repo: string, issue: number, outFile: string, options?: {
     binary?: string | null;
     runFn?: RunGhApiFn;
 }): string;
+/**
+ * Lint a live issue body for mojibake. Returns findings (empty = clean).
+ * Does not throw on hits — callers decide exit code.
+ */
+export declare function lintIssueBody(repo: string, issue: number, options?: {
+    binary?: string | null;
+    runFn?: RunGhApiFn;
+}): Finding[];
+/**
+ * Lint a live PR body for mojibake. Returns findings (empty = clean).
+ */
+export declare function lintPrBody(repo: string, pr: number, options?: {
+    binary?: string | null;
+    runFn?: RunGhApiFn;
+}): Finding[];
 export interface GitHubBodyCliArgs {
     command: string;
     repo?: string;
@@ -55,5 +95,8 @@ export interface GitHubBodyCliArgs {
     bodyFile?: string;
     outFile?: string;
 }
-export declare function githubBodyMain(args: GitHubBodyCliArgs): number;
+export declare function githubBodyMain(args: GitHubBodyCliArgs, options?: {
+    runFn?: RunGhApiFn;
+    binary?: string | null;
+}): number;
 //# sourceMappingURL=github-body.d.ts.map