@deftai/directive-core 0.92.0 → 0.94.0

package/dist/xbrief/create.js

@@ -0,0 +1,285 @@
+/**
+ * xbrief:create — write a dense xBRIEF artifact at --out (#3057).
+ *
+ * Required: --format (json|md|both), --out
+ * Optional: --style, --title, --id, --status, --description, --force, --project-root
+ *
+ * Does NOT move lifecycle folders. Not scope:promote / activate / complete.
+ */
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+import { ContainedWriteError, ContainedWriteErrorCode, containedWrite, } from "../fs/contained-write.js";
+import { validateVbriefSchema } from "../vbrief-validate/schema.js";
+import { resolveXbriefOutPaths, XbriefPathError } from "./paths.js";
+import { buildStyleDocument, renderMarkdown } from "./styles.js";
+import { DEFAULT_XBRIEF_SIZE_CAP_BYTES, isXbriefFormat, isXbriefStyle, } from "./types.js";
+export const CREATE_USAGE = "Usage: deft xbrief:create -- --format <json|md|both> --out <path> [--style <scope|playbook|mission|project>] [--title <t>] [--id <id>] [--status <s>] [--description <d>] [--from-json <path>] [--force] [--project-root <dir>]\n" +
+    "  Write a dense xBRIEF artifact at --out. Required: --format and --out.\n" +
+    "  create ≠ lifecycle: does not promote/activate/complete (use scope:* for lifecycle).\n";
+function fail(stderr, exitCode = 2) {
+    return { exitCode, stdout: "", stderr };
+}
+function parseFlagValue(argv, i, name) {
+    const eq = argv[i]?.startsWith(`${name}=`) ? argv[i].slice(name.length + 1) : undefined;
+    if (eq !== undefined) {
+        if (eq.length === 0)
+            return { error: `argument ${name}: expected one argument\n` };
+        return { value: eq, next: i };
+    }
+    const next = argv[i + 1];
+    if (next === undefined || next.startsWith("-")) {
+        return { error: `argument ${name}: expected one argument\n` };
+    }
+    return { value: next, next: i + 1 };
+}
+/** Parse create CLI argv into options (or error string). */
+export function parseCreateArgv(argv) {
+    let format;
+    let out;
+    let style = "scope";
+    let title;
+    let id;
+    let status;
+    let description;
+    let fromJson;
+    let force = false;
+    let projectRoot = process.cwd();
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === undefined)
+            continue;
+        if (arg === "-h" || arg === "--help") {
+            return { error: CREATE_USAGE };
+        }
+        if (arg === "--force") {
+            force = true;
+            continue;
+        }
+        if (arg === "--format" || arg.startsWith("--format=")) {
+            const parsed = parseFlagValue(argv, i, "--format");
+            if ("error" in parsed)
+                return parsed;
+            format = parsed.value;
+            i = parsed.next;
+            continue;
+        }
+        if (arg === "--out" || arg.startsWith("--out=")) {
+            const parsed = parseFlagValue(argv, i, "--out");
+            if ("error" in parsed)
+                return parsed;
+            out = parsed.value;
+            i = parsed.next;
+            continue;
+        }
+        if (arg === "--style" || arg.startsWith("--style=")) {
+            const parsed = parseFlagValue(argv, i, "--style");
+            if ("error" in parsed)
+                return parsed;
+            style = parsed.value;
+            i = parsed.next;
+            continue;
+        }
+        if (arg === "--title" || arg.startsWith("--title=")) {
+            const parsed = parseFlagValue(argv, i, "--title");
+            if ("error" in parsed)
+                return parsed;
+            title = parsed.value;
+            i = parsed.next;
+            continue;
+        }
+        if (arg === "--id" || arg.startsWith("--id=")) {
+            const parsed = parseFlagValue(argv, i, "--id");
+            if ("error" in parsed)
+                return parsed;
+            id = parsed.value;
+            i = parsed.next;
+            continue;
+        }
+        if (arg === "--status" || arg.startsWith("--status=")) {
+            const parsed = parseFlagValue(argv, i, "--status");
+            if ("error" in parsed)
+                return parsed;
+            status = parsed.value;
+            i = parsed.next;
+            continue;
+        }
+        if (arg === "--description" || arg.startsWith("--description=")) {
+            const parsed = parseFlagValue(argv, i, "--description");
+            if ("error" in parsed)
+                return parsed;
+            description = parsed.value;
+            i = parsed.next;
+            continue;
+        }
+        if (arg === "--from-json" || arg.startsWith("--from-json=")) {
+            const parsed = parseFlagValue(argv, i, "--from-json");
+            if ("error" in parsed)
+                return parsed;
+            fromJson = parsed.value;
+            i = parsed.next;
+            continue;
+        }
+        if (arg === "--project-root" || arg.startsWith("--project-root=")) {
+            const parsed = parseFlagValue(argv, i, "--project-root");
+            if ("error" in parsed)
+                return parsed;
+            projectRoot = parsed.value;
+            i = parsed.next;
+            continue;
+        }
+        if (arg === "--")
+            continue;
+        return { error: `unrecognized argument: ${arg}\n${CREATE_USAGE}` };
+    }
+    if (format === undefined) {
+        return { error: `missing required --format (json|md|both)\n${CREATE_USAGE}` };
+    }
+    if (!isXbriefFormat(format)) {
+        return { error: `invalid --format ${format} (expected json|md|both)\n${CREATE_USAGE}` };
+    }
+    if (out === undefined || out.length === 0) {
+        return { error: `missing required --out\n${CREATE_USAGE}` };
+    }
+    if (!isXbriefStyle(style)) {
+        return {
+            error: `invalid --style ${style} (expected scope|playbook|mission|project)\n${CREATE_USAGE}`,
+        };
+    }
+    return {
+        format,
+        out,
+        style,
+        title,
+        id,
+        status,
+        description,
+        fromJson,
+        force,
+        projectRoot,
+    };
+}
+function loadFromJson(path) {
+    try {
+        const raw = readFileSync(path, "utf8");
+        const data = JSON.parse(raw);
+        if (typeof data !== "object" || data === null || Array.isArray(data)) {
+            return { ok: false, error: `--from-json must be a JSON object: ${path}\n` };
+        }
+        return { ok: true, doc: data };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `failed to read --from-json ${path}: ${msg}\n` };
+    }
+}
+function defaultTitle(style, outStem) {
+    const base = basename(outStem);
+    if (base.length > 0)
+        return base;
+    return `Untitled ${style}`;
+}
+/** Core create implementation (testable). */
+export function createXbrief(options) {
+    let paths;
+    try {
+        paths = resolveXbriefOutPaths({
+            projectRoot: options.projectRoot,
+            out: options.out,
+            format: options.format,
+            cwd: options.cwd,
+            home: options.home,
+            env: options.env,
+        });
+    }
+    catch (err) {
+        if (err instanceof XbriefPathError) {
+            return fail(`${err.message}\n`, 1);
+        }
+        throw err;
+    }
+    let doc;
+    if (options.fromJson !== undefined) {
+        const loaded = loadFromJson(options.fromJson);
+        if (!loaded.ok)
+            return fail(loaded.error, 1);
+        doc = loaded.doc;
+    }
+    else {
+        const title = options.title ?? defaultTitle(options.style, paths.stemAbs);
+        doc = buildStyleDocument({
+            style: options.style,
+            title,
+            id: options.id,
+            status: options.status,
+            description: options.description,
+            now: options.now,
+        });
+    }
+    const schemaErrors = validateVbriefSchema(doc, paths.stemAbs);
+    if (schemaErrors.length > 0) {
+        return fail(`xbrief:create schema invalid:\n${schemaErrors.map((e) => `  - ${e}`).join("\n")}\n`, 1);
+    }
+    const sizeCap = options.sizeCapBytes ?? DEFAULT_XBRIEF_SIZE_CAP_BYTES;
+    const jsonText = `${JSON.stringify(doc, null, 2)}\n`;
+    const mdText = renderMarkdown(doc, options.style);
+    if (Buffer.byteLength(jsonText, "utf8") > sizeCap) {
+        return fail(`xbrief:create refused: json payload exceeds size cap (${sizeCap} bytes)\n`, 1);
+    }
+    if (Buffer.byteLength(mdText, "utf8") > sizeCap) {
+        return fail(`xbrief:create refused: md payload exceeds size cap (${sizeCap} bytes)\n`, 1);
+    }
+    const mode = options.force === true ? "replace" : "create";
+    const written = [];
+    try {
+        if (paths.jsonAbs !== null) {
+            containedWrite({
+                root: paths.projectRoot,
+                target: paths.jsonAbs,
+                data: jsonText,
+                mode,
+            });
+            written.push(paths.jsonAbs);
+        }
+        if (paths.mdAbs !== null) {
+            containedWrite({
+                root: paths.projectRoot,
+                target: paths.mdAbs,
+                data: mdText,
+                mode,
+            });
+            written.push(paths.mdAbs);
+        }
+    }
+    catch (err) {
+        if (err instanceof ContainedWriteError) {
+            if (err.code === ContainedWriteErrorCode.EXISTS) {
+                return fail(`xbrief:create refused: target exists (${err.target}); pass --force to replace\n`, 1);
+            }
+            if (err.code === ContainedWriteErrorCode.ESCAPE) {
+                return fail(`xbrief:create path refused: ${err.message}\n`, 1);
+            }
+            return fail(`xbrief:create write failed: ${err.message}\n`, 1);
+        }
+        throw err;
+    }
+    const lines = [
+        `OK xbrief:create format=${options.format} style=${options.style}`,
+        ...written.map((p) => `  wrote ${p}`),
+        "  note: create is not a lifecycle move (scope:* handles promote/activate/complete)",
+    ];
+    return { exitCode: 0, stdout: `${lines.join("\n")}\n`, stderr: "" };
+}
+/** CLI entry for dispatch wrapper. */
+export function runXbriefCreateCli(argv) {
+    const parsed = parseCreateArgv(argv);
+    if ("error" in parsed) {
+        const isHelp = parsed.error === CREATE_USAGE;
+        return {
+            exitCode: isHelp ? 0 : 2,
+            stdout: isHelp ? CREATE_USAGE : "",
+            stderr: isHelp ? "" : parsed.error,
+        };
+    }
+    return createXbrief(parsed);
+}
+//# sourceMappingURL=create.js.map

package/dist/xbrief/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * On-demand xBRIEF create/verify surface (#3057).
+ *
+ * create/verify write or check dense SoT artifacts at --out.
+ * Scope lifecycle remains scope:promote / activate / complete / etc.
+ */
+export { CREATE_USAGE, type CreateOptions, createXbrief, parseCreateArgv, runXbriefCreateCli, } from "./create.js";
+export { expandUserPath, resolveXbriefOutPaths, stripXbriefSuffix, XbriefPathError, } from "./paths.js";
+export { type BuildDocumentInput, buildStyleDocument, MD_REQUIRED_SECTIONS, parseMarkdownMeta, renderMarkdown, } from "./styles.js";
+export { DEFAULT_XBRIEF_SIZE_CAP_BYTES, isXbriefFormat, isXbriefStyle, XBRIEF_FORMATS, XBRIEF_STYLES, type XbriefCliResult, type XbriefDocument, type XbriefFormat, type XbriefPaths, type XbriefStyle, } from "./types.js";
+export { parseVerifyArgv, runXbriefVerifyCli, VERIFY_USAGE, type VerifyOptions, verifyXbrief, } from "./verify.js";
+/** Dispatch-compatible main for a combined xbrief-cli module (create|verify). */
+export declare function main(argv?: string[]): number;
+//# sourceMappingURL=index.d.ts.map

package/dist/xbrief/index.js

@@ -0,0 +1,42 @@
+/**
+ * On-demand xBRIEF create/verify surface (#3057).
+ *
+ * create/verify write or check dense SoT artifacts at --out.
+ * Scope lifecycle remains scope:promote / activate / complete / etc.
+ */
+import { runXbriefCreateCli } from "./create.js";
+import { runXbriefVerifyCli } from "./verify.js";
+export { CREATE_USAGE, createXbrief, parseCreateArgv, runXbriefCreateCli, } from "./create.js";
+export { expandUserPath, resolveXbriefOutPaths, stripXbriefSuffix, XbriefPathError, } from "./paths.js";
+export { buildStyleDocument, MD_REQUIRED_SECTIONS, parseMarkdownMeta, renderMarkdown, } from "./styles.js";
+export { DEFAULT_XBRIEF_SIZE_CAP_BYTES, isXbriefFormat, isXbriefStyle, XBRIEF_FORMATS, XBRIEF_STYLES, } from "./types.js";
+export { parseVerifyArgv, runXbriefVerifyCli, VERIFY_USAGE, verifyXbrief, } from "./verify.js";
+/** Dispatch-compatible main for a combined xbrief-cli module (create|verify). */
+export function main(argv = process.argv.slice(2)) {
+    const [verb, ...rest] = argv;
+    if (verb === "create") {
+        const result = runXbriefCreateCli(rest);
+        if (result.stdout)
+            process.stdout.write(result.stdout);
+        if (result.stderr)
+            process.stderr.write(result.stderr);
+        return result.exitCode;
+    }
+    if (verb === "verify") {
+        const result = runXbriefVerifyCli(rest);
+        if (result.stdout)
+            process.stdout.write(result.stdout);
+        if (result.stderr)
+            process.stderr.write(result.stderr);
+        return result.exitCode;
+    }
+    if (verb === "-h" || verb === "--help" || verb === undefined) {
+        process.stdout.write("Usage: deft xbrief:create|xbrief:verify -- --format <json|md|both> --out <path> [options]\n" +
+            "  create/verify dense xBRIEF artifacts (not scope lifecycle).\n" +
+            "  See: deft xbrief:create --help | deft xbrief:verify --help\n");
+        return verb === undefined ? 2 : 0;
+    }
+    process.stderr.write(`unknown xbrief subcommand: ${verb}\n`);
+    return 2;
+}
+//# sourceMappingURL=index.js.map

package/dist/xbrief/paths.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Portable path expand + project-root containment for xbrief:create/verify (#3057).
+ *
+ * Uses real path APIs (node:path / node:os) — no slash-only logic.
+ * Default containment under project root fails closed on escape.
+ */
+import type { XbriefFormat, XbriefPaths } from "./types.js";
+export declare class XbriefPathError extends Error {
+    readonly code: string;
+    constructor(message: string, code?: string);
+}
+/**
+ * Expand simple user path forms portably:
+ * - `~` / `~/…` / `~\…` → home directory
+ * - `%VAR%` (Windows-class env expansion) when present in the string
+ *
+ * Relative paths are left relative (caller resolves against project root or cwd).
+ */
+export declare function expandUserPath(input: string, options?: {
+    home?: string;
+    env?: NodeJS.ProcessEnv;
+}): string;
+/** Strip known xBRIEF suffixes to recover a write stem. */
+export declare function stripXbriefSuffix(pathLike: string): string;
+/**
+ * Resolve `--out` under `projectRoot` with user-path expansion and fail-closed
+ * containment. Returns absolute stem + format-specific artifact paths.
+ */
+export declare function resolveXbriefOutPaths(input: {
+    projectRoot: string;
+    out: string;
+    format: XbriefFormat;
+    cwd?: string;
+    home?: string;
+    env?: NodeJS.ProcessEnv;
+}): XbriefPaths;
+//# sourceMappingURL=paths.d.ts.map

package/dist/xbrief/paths.js

@@ -0,0 +1,123 @@
+/**
+ * Portable path expand + project-root containment for xbrief:create/verify (#3057).
+ *
+ * Uses real path APIs (node:path / node:os) — no slash-only logic.
+ * Default containment under project root fails closed on escape.
+ */
+import { homedir } from "node:os";
+import { isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
+import { ContainedWriteError, ContainedWriteErrorCode, resolveContainedTarget, } from "../fs/contained-write.js";
+export class XbriefPathError extends Error {
+    code;
+    constructor(message, code = "XBRIEF_PATH_ERROR") {
+        super(message);
+        this.name = "XbriefPathError";
+        this.code = code;
+    }
+}
+/**
+ * Expand simple user path forms portably:
+ * - `~` / `~/…` / `~\…` → home directory
+ * - `%VAR%` (Windows-class env expansion) when present in the string
+ *
+ * Relative paths are left relative (caller resolves against project root or cwd).
+ */
+export function expandUserPath(input, options = {}) {
+    if (input.length === 0) {
+        throw new XbriefPathError("empty path", "XBRIEF_PATH_EMPTY");
+    }
+    const home = options.home ?? homedir();
+    const env = options.env ?? process.env;
+    let expanded = input.replace(/%([^%]+)%/g, (match, name) => {
+        const value = env[name];
+        return value !== undefined && value.length > 0 ? value : match;
+    });
+    if (expanded === "~") {
+        expanded = home;
+    }
+    else if (expanded.startsWith("~/") || expanded.startsWith("~\\")) {
+        expanded = join(home, expanded.slice(2));
+    }
+    // Env expansion may inject foreign separators (e.g. %USERPROFILE%\foo on Linux CI).
+    // Re-normalize with path.normalize after collapsing to platform-native separators.
+    const collapsed = expanded.replace(/\\/g, "/");
+    return normalize(collapsed);
+}
+/** Strip known xBRIEF suffixes to recover a write stem. */
+export function stripXbriefSuffix(pathLike) {
+    const lower = pathLike.toLowerCase();
+    if (lower.endsWith(".xbrief.json")) {
+        return pathLike.slice(0, -".xbrief.json".length);
+    }
+    if (lower.endsWith(".xbrief.md")) {
+        return pathLike.slice(0, -".xbrief.md".length);
+    }
+    return pathLike;
+}
+/**
+ * Resolve `--out` under `projectRoot` with user-path expansion and fail-closed
+ * containment. Returns absolute stem + format-specific artifact paths.
+ */
+export function resolveXbriefOutPaths(input) {
+    const projectRoot = resolve(input.projectRoot);
+    const expanded = expandUserPath(input.out, { home: input.home, env: input.env });
+    // Absolute (post-expand) paths must still nest under projectRoot.
+    // Relative paths resolve against projectRoot (not bare cwd) so containment is stable.
+    let candidate;
+    if (isAbsolute(expanded)) {
+        candidate = resolve(expanded);
+    }
+    else {
+        // When out is explicitly cwd-relative (./…), resolve against cwd then re-check root.
+        const cwd = input.cwd ?? process.cwd();
+        if (expanded === "." ||
+            expanded.startsWith(`.${sep}`) ||
+            expanded.startsWith("./") ||
+            expanded.startsWith(".\\")) {
+            candidate = resolve(cwd, expanded);
+        }
+        else {
+            candidate = resolve(projectRoot, expanded);
+        }
+    }
+    const stemRaw = stripXbriefSuffix(candidate);
+    let stemAbs;
+    try {
+        // resolveContainedTarget requires nested path (not the root itself).
+        // If stem equals root, fail with a clear message.
+        const rel = relative(projectRoot, stemAbsPlaceholder(projectRoot, stemRaw));
+        if (rel.length === 0) {
+            throw new XbriefPathError(`xbrief path refused: --out resolves to project root (need a file stem under the root)`, "XBRIEF_PATH_ESCAPE");
+        }
+        stemAbs = resolveContainedTarget(projectRoot, isAbsolute(stemRaw) ? stemRaw : relative(projectRoot, stemRaw));
+    }
+    catch (err) {
+        if (err instanceof XbriefPathError)
+            throw err;
+        if (err instanceof ContainedWriteError) {
+            throw new XbriefPathError(`xbrief path refused: --out escapes project root (${err.target})`, err.code === ContainedWriteErrorCode.ESCAPE ? "XBRIEF_PATH_ESCAPE" : err.code);
+        }
+        throw err;
+    }
+    const jsonAbs = input.format === "md" ? null : `${stemAbs}.xbrief.json`;
+    const mdAbs = input.format === "json" ? null : `${stemAbs}.xbrief.md`;
+    // Re-validate artifact paths under root (stem + suffix must stay nested).
+    for (const p of [jsonAbs, mdAbs]) {
+        if (p === null)
+            continue;
+        try {
+            resolveContainedTarget(projectRoot, p);
+        }
+        catch (err) {
+            if (err instanceof ContainedWriteError) {
+                throw new XbriefPathError(`xbrief path refused: artifact escapes project root (${p})`, "XBRIEF_PATH_ESCAPE");
+            }
+            throw err;
+        }
+    }
+    return { projectRoot, stemAbs, jsonAbs, mdAbs };
+}
+function stemAbsPlaceholder(projectRoot, stemRaw) {
+    return isAbsolute(stemRaw) ? resolve(stemRaw) : resolve(projectRoot, stemRaw);
+}
+//# sourceMappingURL=paths.js.map

package/dist/xbrief/styles.d.ts

@@ -0,0 +1,36 @@
+/**
+ * P0 xBRIEF style templates and markdown section maps (#3057).
+ *
+ * One schema spine (xBRIEF v0.8); markdown is a dense render of the same plan,
+ * not a second dialect.
+ */
+import type { XbriefDocument, XbriefStyle } from "./types.js";
+/** Required H2 section titles in the markdown form per style. */
+export declare const MD_REQUIRED_SECTIONS: Readonly<Record<XbriefStyle, readonly string[]>>;
+export interface BuildDocumentInput {
+    style: XbriefStyle;
+    title: string;
+    id?: string;
+    status?: string;
+    description?: string;
+    now?: Date;
+    /** Optional narrative overrides merged over style defaults. */
+    narratives?: Record<string, string>;
+    items?: unknown[];
+}
+/** Build a minimal valid xBRIEF v0.8 document for the given P0 style. */
+export declare function buildStyleDocument(input: BuildDocumentInput): XbriefDocument;
+/** Render dense markdown from the JSON spine (one dialect). */
+export declare function renderMarkdown(doc: XbriefDocument, style: XbriefStyle): string;
+/**
+ * Lightweight parse of md form for verify: extract title, status, id, and H2 sections.
+ * Not a full reverse dialect — verify uses it for required-section + consistency checks.
+ */
+export declare function parseMarkdownMeta(md: string): {
+    title: string | null;
+    status: string | null;
+    id: string | null;
+    style: string | null;
+    sections: Set<string>;
+};
+//# sourceMappingURL=styles.d.ts.map