@deftai/directive-core 0.59.0 → 0.60.0

package/dist/deposit/python-free.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Python-free deposit hygiene (#2022 Phase 3).
+ *
+ * After copying @deftai/directive-content into `.deft/core`, strip any
+ * Python-only artifacts that must not ship to npm consumers: the legacy
+ * `scripts/` tree, `.py` files, and Python `run` shims.
+ */
+export interface PythonArtifact {
+    readonly path: string;
+    readonly kind: "py-file" | "scripts-tree" | "run-shim";
+}
+/** List Python-only artifacts under a deposit root (relative paths). */
+export declare function collectPythonArtifacts(depositDir: string): PythonArtifact[];
+/** Return true when a repo-root `run` file is a Python launcher shim. */
+export declare function isRepoRootPythonRunShim(projectDir: string): boolean;
+export interface PrunePythonArtifactsIo {
+    printf: (text: string) => void;
+}
+/** Remove Python-only trees/files from the consumer deposit and repo-root run shim. */
+export declare function prunePythonArtifactsFromDeposit(depositDir: string, projectDir: string, io?: PrunePythonArtifactsIo): Promise<number>;
+//# sourceMappingURL=python-free.d.ts.map

package/dist/deposit/python-free.js

@@ -0,0 +1,149 @@
+/**
+ * Python-free deposit hygiene (#2022 Phase 3).
+ *
+ * After copying @deftai/directive-content into `.deft/core`, strip any
+ * Python-only artifacts that must not ship to npm consumers: the legacy
+ * `scripts/` tree, `.py` files, and Python `run` shims.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { readdir, readFile, rm, stat } from "node:fs/promises";
+import { join, relative } from "node:path";
+const PY_SUFFIX = ".py";
+const PYC_SUFFIX = ".pyc";
+function isPythonRunShim(_path, head) {
+    if (!head.startsWith("#!"))
+        return false;
+    const bang = head.split("\n", 1)[0] ?? head;
+    return /python/i.test(bang);
+}
+function walkForPyFilesSync(root, base, found) {
+    let entries;
+    try {
+        entries = readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const full = join(root, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name === "__pycache__") {
+                found.push({ path: relative(base, full), kind: "py-file" });
+                continue;
+            }
+            walkForPyFilesSync(full, base, found);
+            continue;
+        }
+        if (!entry.isFile())
+            continue;
+        if (entry.name.endsWith(PY_SUFFIX) || entry.name.endsWith(PYC_SUFFIX)) {
+            found.push({ path: relative(base, full), kind: "py-file" });
+        }
+    }
+}
+/** List Python-only artifacts under a deposit root (relative paths). */
+export function collectPythonArtifacts(depositDir) {
+    const found = [];
+    const scriptsDir = join(depositDir, "scripts");
+    try {
+        if (statSync(scriptsDir).isDirectory()) {
+            found.push({ path: "scripts", kind: "scripts-tree" });
+        }
+    }
+    catch {
+        // absent
+    }
+    const runPath = join(depositDir, "run");
+    if (existsSync(runPath)) {
+        try {
+            const head = readFileSync(runPath, "utf8");
+            if (isPythonRunShim(runPath, head.slice(0, 200))) {
+                found.push({ path: "run", kind: "run-shim" });
+            }
+        }
+        catch {
+            found.push({ path: "run", kind: "run-shim" });
+        }
+    }
+    walkForPyFilesSync(depositDir, depositDir, found);
+    return found;
+}
+/** Return true when a repo-root `run` file is a Python launcher shim. */
+export function isRepoRootPythonRunShim(projectDir) {
+    const runPath = join(projectDir, "run");
+    if (!existsSync(runPath))
+        return false;
+    try {
+        const head = readFileSync(runPath, "utf8").slice(0, 200);
+        return isPythonRunShim(runPath, head);
+    }
+    catch {
+        return true;
+    }
+}
+/** Remove Python-only trees/files from the consumer deposit and repo-root run shim. */
+export async function prunePythonArtifactsFromDeposit(depositDir, projectDir, io) {
+    let removed = 0;
+    const scriptsDir = join(depositDir, "scripts");
+    try {
+        if ((await stat(scriptsDir)).isDirectory()) {
+            await rm(scriptsDir, { recursive: true, force: true });
+            removed += 1;
+            io?.printf("Removed Python scripts/ tree from the consumer deposit (#2022 Phase 3).\n");
+        }
+    }
+    catch {
+        // absent
+    }
+    async function walkRemovePy(root) {
+        let entries;
+        try {
+            entries = await readdir(root, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const full = join(root, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name === "__pycache__") {
+                    await rm(full, { recursive: true, force: true });
+                    removed += 1;
+                    continue;
+                }
+                await walkRemovePy(full);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            if (entry.name.endsWith(PY_SUFFIX) || entry.name.endsWith(PYC_SUFFIX)) {
+                await rm(full, { force: true });
+                removed += 1;
+            }
+        }
+    }
+    await walkRemovePy(depositDir);
+    const depositRun = join(depositDir, "run");
+    if (existsSync(depositRun)) {
+        try {
+            const head = await readFile(depositRun, "utf8");
+            if (isPythonRunShim(depositRun, head.slice(0, 200))) {
+                await rm(depositRun, { force: true });
+                removed += 1;
+                io?.printf("Removed Python run shim from .deft/core (#2022 Phase 3).\n");
+            }
+        }
+        catch {
+            await rm(depositRun, { force: true });
+            removed += 1;
+        }
+    }
+    const projectRun = join(projectDir, "run");
+    if (isRepoRootPythonRunShim(projectDir)) {
+        await rm(projectRun, { force: true });
+        removed += 1;
+        io?.printf("Removed repo-root Python run shim (#2022 Phase 3).\n");
+    }
+    return removed;
+}
+//# sourceMappingURL=python-free.js.map

package/dist/doctor/constants.d.ts

@@ -8,6 +8,8 @@ export declare const REDIRECT_STUB_HEADER_LINES = 8;
 export declare const TASKFILE_INCLUDE_SNIPPET = "version: '3'\n\nincludes:\n  deft:\n    taskfile: ./.deft/core/Taskfile.yml\n    optional: true\n";
 export declare const DOCTOR_ALLOWED_FLAGS: readonly ["--session", "--fix", "--repair", "--repair-taskfile", "--json", "--quiet", "--full", "--project-root", "-h", "--help"];
 export declare const EXPECTED_FRAMEWORK_DIRS: readonly ["tasks", "scripts", "vbrief"];
+/** npm consumer deposit after #2022 Phase 3 -- Python scripts/ tree is intentionally absent. */
+export declare const CONSUMER_FRAMEWORK_DIRS: readonly ["tasks", "vbrief"];
 export declare const DEFT_REPO_POSITIVE_MARKERS: readonly ["content/templates/agents-entry.md", "content/skills/deft-directive-build/SKILL.md"];
 export declare const EXPECTED_CONTENT_DIRS: readonly ["languages", "strategies", "skills", "templates"];
 /** Post-freeze canonical upgrade path (#1997 / #2003 / #1912). */

package/dist/doctor/constants.js

@@ -27,6 +27,8 @@ export const DOCTOR_ALLOWED_FLAGS = [
 // Engine / lifecycle dirs that stay at the framework root (NOT relocated by
 // #1875). Shippable-content dirs moved under content/ -- see EXPECTED_CONTENT_DIRS.
 export const EXPECTED_FRAMEWORK_DIRS = ["tasks", "scripts", "vbrief"];
+/** npm consumer deposit after #2022 Phase 3 -- Python scripts/ tree is intentionally absent. */
+export const CONSUMER_FRAMEWORK_DIRS = ["tasks", "vbrief"];
 // Post-#1875 content/ move: these framework-internal markers now live under
 // content/ in the SOURCE repo. They identify a deft source checkout (a consumer
 // would never reproduce them); the C1 flatten means a consumer deposit has no

package/dist/doctor/main.js

@@ -1,12 +1,13 @@
 import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { contentRoot } from "../content-root.js";
 import { agentsRefreshPlan, hasV3ManagedMarker } from "./agents-md.js";
 import { runChecks } from "./checks.js";
-import { EXPECTED_CONTENT_DIRS, EXPECTED_FRAMEWORK_DIRS, TASKFILE_INCLUDE_SNIPPET, UV_INSTALL_URL, } from "./constants.js";
+import { CONSUMER_FRAMEWORK_DIRS, EXPECTED_CONTENT_DIRS, EXPECTED_FRAMEWORK_DIRS, TASKFILE_INCLUDE_SNIPPET, UV_INSTALL_URL, } from "./constants.js";
 import { decideThrottle, formatIsoZ, readState, renderDoctorStatusLine, writeState, } from "./doctor-state.js";
 import { formatAllowedFlagsHint, formatUnknownFlagsError, parseDoctorFlags } from "./flags.js";
 import { pythonJsonDump } from "./json.js";
+import { parseInstallRootFromAgentsMd } from "./manifest.js";
 import { createPlainSink } from "./output.js";
 import { resolveDefaultFrameworkRoot, resolvePath, resolveVersion, runningInsideDeftRepo, } from "./paths.js";
 import { runPayloadStalenessCheck } from "./payload-staleness.js";
@@ -28,6 +29,7 @@ export function cmdDoctor(args, seams = {}) {
     const fullMode = flags.full;
     const projectRoot = resolvePath(flags.projectRoot ?? process.cwd());
     const frameworkRoot = seams.frameworkRoot ?? resolveDefaultFrameworkRoot();
+    const consumerContext = resolve(projectRoot) !== resolve(frameworkRoot);
     const whichFn = seams.whichFn ?? defaultWhich;
     const nowFn = seams.now ?? (() => new Date());
     if (!fullMode) {
@@ -108,11 +110,13 @@ export function cmdDoctor(args, seams = {}) {
             suggestion: installUrl || null,
         });
     };
-    checkCommand("uv", "uv (Astral Python runner)", true, UV_INSTALL_URL);
+    if (!consumerContext) {
+        checkCommand("uv", "uv (Astral Python runner)", true, UV_INSTALL_URL);
+        checkCommand("python3", "python3");
+        checkCommand("go", "go");
+    }
     checkCommand("git", "git", true);
-    checkCommand("python3", "python3");
-    checkCommand("go", "go");
-    checkCommand("node", "node");
+    checkCommand("node", "node", consumerContext);
     if (!jsonMode) {
         sink.blank();
     }
@@ -149,10 +153,20 @@ export function cmdDoctor(args, seams = {}) {
     // #1875: shippable-content dirs resolve under content/ in a source checkout
     // and at the root in a flattened consumer deposit; engine/lifecycle dirs stay
     // at the framework root in both layouts.
-    const contentBase = contentRoot(frameworkRoot);
+    let agentsMdText = "";
+    try {
+        agentsMdText = readFileSync(join(projectRoot, "AGENTS.md"), "utf8");
+    }
+    catch {
+        agentsMdText = "";
+    }
+    const installRootRel = parseInstallRootFromAgentsMd(agentsMdText) ?? ".deft/core";
+    const depositRoot = consumerContext ? join(projectRoot, installRootRel) : frameworkRoot;
+    const contentBase = contentRoot(depositRoot);
+    const frameworkDirs = consumerContext ? CONSUMER_FRAMEWORK_DIRS : EXPECTED_FRAMEWORK_DIRS;
     const layoutChecks = [
         ...EXPECTED_CONTENT_DIRS.map((d) => [d, contentBase]),
-        ...EXPECTED_FRAMEWORK_DIRS.map((d) => [d, frameworkRoot]),
+        ...frameworkDirs.map((d) => [d, depositRoot]),
     ];
     for (const [dirName, base] of layoutChecks) {
         const dirPath = join(base, dirName);

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

@@ -9,6 +9,7 @@ import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { homedir, platform } from "node:os";
 import { join, resolve } from "node:path";
 import { copyTree } from "../deposit/copy-tree.js";
+import { prunePythonArtifactsFromDeposit } from "../deposit/python-free.js";
 import { resolveInstalledContentRoot } from "../deposit/resolve-content.js";
 import { readCorePackageVersion } from "../engine-version.js";
 import { ensureInitGitignoreLines, reconstituteDepositFromContent } from "./gitignore.js";
@@ -124,6 +125,7 @@ export async function runInitDeposit(args, io, seams = {}) {
     const copyContent = seams.copyContent ?? copyTree;
     const contentRoot = await resolveContent();
     await reconstituteDepositFromContent(contentRoot, deftDir, copyContent);
+    await prunePythonArtifactsFromDeposit(deftDir, projectDir, io);
     ensureInitGitignoreLines(projectDir, io);
     const nowIso = seams.nowIso ?? (() => new Date().toISOString().replace(/\.\d{3}Z$/, "Z"));
     const version = readContentVersion(contentRoot, seams.readPackageVersion ?? readCorePackageVersion);

package/dist/init-deposit/refresh.js

@@ -10,6 +10,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { copyTree } from "../deposit/copy-tree.js";
+import { prunePythonArtifactsFromDeposit } from "../deposit/python-free.js";
 import { resolveInstalledContentRoot } from "../deposit/resolve-content.js";
 import { manifestTagToVersion, parseInstallManifest } from "../doctor/manifest.js";
 import { readCorePackageVersion } from "../engine-version.js";
@@ -211,6 +212,7 @@ export async function runRefreshDeposit(args, io, seams = {}) {
     const contentVersion = readContentPackageVersion(contentRoot, readPackageVersion);
     const versionSkewNotice = buildVersionSkewNotice(engineVersion, contentVersion, previousDepositVersion);
     await copyContent(contentRoot, deftDir);
+    await prunePythonArtifactsFromDeposit(deftDir, projectDir, io);
     const nowIso = seams.nowIso ?? (() => new Date().toISOString().replace(/\.\d{3}Z$/, "Z"));
     const manifestFields = {
         ref: contentVersion.startsWith("v") ? contentVersion : `v${contentVersion}`,

package/dist/install-upgrade/index.d.ts

@@ -0,0 +1,11 @@
+export interface InstallUpgradeArgs {
+    readonly projectRoot: string;
+    readonly frameworkRoot: string;
+}
+export interface InstallUpgradeIo {
+    writeOut: (text: string) => void;
+    writeErr: (text: string) => void;
+}
+/** Port of ``run upgrade`` / ``task install:upgrade`` for the consumer task surface (#1061 / #2022). */
+export declare function runInstallUpgrade(args: InstallUpgradeArgs, io: InstallUpgradeIo): number;
+//# sourceMappingURL=index.d.ts.map

package/dist/install-upgrade/index.js

@@ -0,0 +1,146 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { manifestTagToVersion, parseInstallManifest } from "../doctor/manifest.js";
+import { buildInstallManifestText, CANONICAL_INSTALL_ROOT, } from "../init-deposit/scaffold.js";
+import { agentsRefreshPlan } from "../platform/agents-md.js";
+import { DEV_FALLBACK } from "../platform/constants.js";
+import { resolveVersion } from "../platform/resolve-version.js";
+import { detectPreCutoverLegacy } from "../vbrief-validate/precutover.js";
+function versionMarkerPaths(projectRoot) {
+    return [join(projectRoot, "vbrief", ".deft-version"), join(projectRoot, ".deft-version")];
+}
+function readVersionMarker(projectRoot) {
+    for (const candidate of versionMarkerPaths(projectRoot)) {
+        if (!existsSync(candidate) || !statSync(candidate).isFile())
+            continue;
+        try {
+            const value = readFileSync(candidate, "utf8").trim();
+            if (value)
+                return value;
+        }
+        catch {
+            // try next candidate
+        }
+    }
+    return null;
+}
+function writeVersionMarker(targetDir, version) {
+    if (version === DEV_FALLBACK)
+        return;
+    try {
+        mkdirSync(targetDir, { recursive: true });
+        writeFileSync(join(targetDir, ".deft-version"), `${version}\n`, "utf8");
+    }
+    catch {
+        // best-effort, mirrors Python
+    }
+}
+function deriveInstallRootString(installRoot, projectRoot) {
+    try {
+        return relative(projectRoot, installRoot).split("\\").join("/") || CANONICAL_INSTALL_ROOT;
+    }
+    catch {
+        return resolve(installRoot).split("\\").join("/");
+    }
+}
+function writeInstallManifestAt(installRoot, projectRoot, version) {
+    if (version.replace(/^v/, "") === DEV_FALLBACK)
+        return null;
+    const fields = {
+        ref: version.startsWith("v") ? version : `v${version}`,
+        sha: "content-package",
+        tag: version.startsWith("v") ? version : `v${version}`,
+        installRoot: deriveInstallRootString(installRoot, projectRoot),
+        fetchedAt: new Date().toISOString().replace(/\.\d{3}Z$/, "Z"),
+        fetchedBy: "deft-upgrade",
+    };
+    try {
+        mkdirSync(installRoot, { recursive: true });
+        const body = buildInstallManifestText(fields);
+        const path = join(installRoot, "VERSION");
+        writeFileSync(path, body, "utf8");
+        return path;
+    }
+    catch {
+        return null;
+    }
+}
+function migrateLegacyInstallManifest(projectRoot, canonicalManifestPath) {
+    if (canonicalManifestPath === null)
+        return;
+    const canonical = resolve(canonicalManifestPath);
+    const expectedParent = resolve(projectRoot, ".deft", "core");
+    if (resolve(canonical, "..") !== expectedParent)
+        return;
+    const legacy = join(projectRoot, ".deft", "VERSION");
+    if (!existsSync(legacy) || !statSync(legacy).isFile())
+        return;
+    try {
+        const legacyVersion = manifestTagToVersion(parseInstallManifest(readFileSync(legacy, "utf8")));
+        const canonicalVersion = manifestTagToVersion(parseInstallManifest(readFileSync(canonical, "utf8")));
+        if (legacyVersion !== null && legacyVersion === canonicalVersion)
+            return;
+        renameSync(legacy, join(projectRoot, ".deft", "VERSION.premigrate"));
+    }
+    catch {
+        // best-effort
+    }
+}
+function runAgentsRefresh(projectRoot, frameworkRoot, io) {
+    const plan = agentsRefreshPlan(projectRoot, { frameworkRoot });
+    const state = String(plan.state ?? "unknown");
+    if (state === "current") {
+        io.writeOut("AGENTS.md managed section is current — no changes.\n");
+        return 0;
+    }
+    if (state === "template-missing" || state === "template-malformed" || state === "unreadable") {
+        io.writeErr(`agents:refresh failed: ${state}\n`);
+        return 2;
+    }
+    const newContent = plan.new_content;
+    if (typeof newContent !== "string") {
+        io.writeErr("agents:refresh failed: plan produced no new_content\n");
+        return 2;
+    }
+    const path = String(plan.path ?? join(projectRoot, "AGENTS.md"));
+    writeFileSync(path, newContent, "utf8");
+    io.writeOut(`AGENTS.md updated (state=${state}).\n`);
+    return 0;
+}
+/** Port of ``run upgrade`` / ``task install:upgrade`` for the consumer task surface (#1061 / #2022). */
+export function runInstallUpgrade(args, io) {
+    const projectRoot = resolve(args.projectRoot);
+    const frameworkRoot = resolve(args.frameworkRoot);
+    const version = resolveVersion({ frameworkRoot });
+    const normalizedVersion = version.startsWith("v") ? version.slice(1) : version;
+    io.writeOut(`Deft CLI v${normalizedVersion} - Upgrade\n\n`);
+    const recorded = readVersionMarker(projectRoot);
+    if (recorded === normalizedVersion) {
+        io.writeOut(`Project already at ${normalizedVersion}. Nothing to do.\n`);
+        return runAgentsRefresh(projectRoot, frameworkRoot, io);
+    }
+    const legacy = detectPreCutoverLegacy(projectRoot);
+    if (legacy.length > 0) {
+        io.writeOut(`Pre-v0.20 document model detected (${legacy.join(", ")}). Run \`task migrate:vbrief\` first -- it migrates legacy artifacts and creates the lifecycle folder structure. This command only records the framework version.\n`);
+    }
+    const vbriefDir = join(projectRoot, "vbrief");
+    const targetDir = existsSync(vbriefDir) && statSync(vbriefDir).isDirectory() ? vbriefDir : projectRoot;
+    writeVersionMarker(targetDir, normalizedVersion);
+    let writtenManifestPath = null;
+    for (const installCandidate of [join(projectRoot, ".deft", "core"), join(projectRoot, "deft")]) {
+        if (existsSync(installCandidate) && statSync(installCandidate).isDirectory()) {
+            writtenManifestPath = writeInstallManifestAt(installCandidate, projectRoot, normalizedVersion);
+            break;
+        }
+    }
+    migrateLegacyInstallManifest(projectRoot, writtenManifestPath);
+    if (recorded === null) {
+        io.writeOut(`Recorded framework version ${normalizedVersion} in .deft-version.\n`);
+    }
+    else {
+        io.writeOut(`Updated .deft-version from ${recorded} to ${normalizedVersion}.\n`);
+    }
+    io.writeOut("If legacy SPECIFICATION.md or PROJECT.md content remains, run `task migrate:vbrief` to complete the upgrade.\n");
+    return runAgentsRefresh(projectRoot, frameworkRoot, io);
+}
+//# sourceMappingURL=index.js.map

package/dist/migrate-preflight/index.d.ts

@@ -0,0 +1,36 @@
+export type CheckStatus = "PASS" | "WARN" | "FAIL";
+export interface CheckResult {
+    readonly name: string;
+    readonly status: CheckStatus;
+    readonly message: string;
+}
+export interface MigratePreflightArgs {
+    readonly projectRoot: string;
+    readonly deftRoot: string;
+    readonly quiet: boolean;
+}
+export interface MigratePreflightConfigError {
+    readonly kind: "config";
+    readonly message: string;
+}
+export type MigratePreflightOutcome = {
+    readonly kind: "ready";
+    readonly exitCode: 0 | 1;
+    readonly results: readonly CheckResult[];
+} | MigratePreflightConfigError;
+export declare function checkUv(which?: (cmd: string) => string | null): CheckResult;
+export declare function checkLayout(deftRoot: string, projectRoot: string): CheckResult;
+export declare function checkGitClean(projectRoot: string): CheckResult;
+export declare function checkDocumentModel(projectRoot: string): CheckResult;
+export declare function evaluate(deftRoot: string, projectRoot: string, which?: (cmd: string) => string | null): {
+    exitCode: 0 | 1;
+    results: CheckResult[];
+};
+export declare function formatCheckLine(result: CheckResult): string;
+export declare function runMigratePreflight(args: MigratePreflightArgs): MigratePreflightOutcome;
+export interface MigratePreflightIo {
+    writeOut: (text: string) => void;
+    writeErr: (text: string) => void;
+}
+export declare function emitMigratePreflight(outcome: Exclude<MigratePreflightOutcome, MigratePreflightConfigError>, io: MigratePreflightIo, quiet: boolean): number;
+//# sourceMappingURL=index.d.ts.map