@deftai/directive-core 0.98.1 → 0.100.0

package/dist/decision/schema.js

@@ -0,0 +1,293 @@
+/**
+ * Lightweight structured agent decision log schema (#1396).
+ *
+ * Intent-debt records for significant choices only. Not a full lifecycle xBRIEF
+ * and not a replacement for docs/decisions/ADR-*.md.
+ */
+export const DECISION_SCHEMA_VERSION = "deft.decision.v1";
+/** Directory under project root for standalone (cross-cutting) decision files. */
+export const DECISIONS_DIR_REL = "xbrief/decisions";
+/** Filename suffix for decision records. */
+export const DECISION_FILE_SUFFIX = ".decision.json";
+const CONFIDENCE_VALUES = new Set(["low", "medium", "high"]);
+const RFC_VALUES = new Set([
+    "MUST",
+    "SHOULD",
+    "MAY",
+    "MUST NOT",
+    "SHOULD NOT",
+]);
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function nonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+/** Normalize timestamps to second-precision UTC with trailing Z. */
+export function normalizeTimestamp(raw) {
+    if (raw !== undefined && raw !== null && raw.trim().length > 0) {
+        const parsed = new Date(raw.trim());
+        if (!Number.isNaN(parsed.getTime())) {
+            return parsed.toISOString().replace(/\.\d{3}Z$/, "Z");
+        }
+    }
+    return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+/**
+ * Derive a kebab-case slug from free text (max 64 chars).
+ * Linear-time (no polynomial regex) for CodeQL safety on library input.
+ */
+export function slugifyDecision(text) {
+    const lower = text.trim().toLowerCase();
+    let out = "";
+    let pendingHyphen = false;
+    for (let i = 0; i < lower.length && out.length < 64; i += 1) {
+        const ch = lower[i];
+        const code = ch.charCodeAt(0);
+        const isAlnum = (code >= 48 && code <= 57) || // 0-9
+            (code >= 97 && code <= 122); // a-z
+        if (isAlnum) {
+            if (pendingHyphen && out.length > 0) {
+                out += "-";
+                if (out.length >= 64)
+                    break;
+            }
+            out += ch;
+            pendingHyphen = false;
+        }
+        else {
+            pendingHyphen = true;
+        }
+    }
+    return out.length > 0 ? out : "decision";
+}
+/**
+ * Strip terminal / bidi control chars for safe plaintext list rendering.
+ * Drops C0 (except tab/LF/CR → space), DEL, C1 (U+0080–U+009F), and
+ * Unicode bidi overrides / isolates / embeddings used for deceptive reordering.
+ */
+export function sanitizeForTerminal(text) {
+    let out = "";
+    for (let i = 0; i < text.length; i += 1) {
+        const code = text.charCodeAt(i);
+        // Tab / LF / CR → space (never pass raw control layout to the terminal).
+        if (code === 9 || code === 10 || code === 13) {
+            out += " ";
+            continue;
+        }
+        // C0 + DEL
+        if (code < 32 || code === 127) {
+            continue;
+        }
+        // C1 controls (including when encoded as U+0080–U+009F)
+        if (code >= 0x80 && code <= 0x9f) {
+            continue;
+        }
+        // Bidi control characters (deceptive reordering)
+        // LRE/RLE/PDF/LRO/RLO, LRI/RLI/FSI/PDI, and related marks.
+        if (code === 0x061c || // ALM
+            code === 0x200e || // LRM
+            code === 0x200f || // RLM
+            (code >= 0x202a && code <= 0x202e) || // LRE..RLO
+            (code >= 0x2066 && code <= 0x2069) // LRI..PDI
+        ) {
+            continue;
+        }
+        out += text[i];
+    }
+    return out;
+}
+/** Date prefix YYYY-MM-DD from an ISO timestamp. */
+export function datePrefixFromTimestamp(timestamp) {
+    const m = timestamp.match(/^(\d{4}-\d{2}-\d{2})/);
+    return m?.[1] ?? new Date().toISOString().slice(0, 10);
+}
+/** Build standalone filename: YYYY-MM-DD-<slug>.decision.json */
+export function decisionFilename(id, timestamp) {
+    const date = datePrefixFromTimestamp(timestamp);
+    const slug = slugifyDecision(id);
+    return `${date}-${slug}${DECISION_FILE_SUFFIX}`;
+}
+/** Validate and normalize an unknown JSON value into a DecisionRecord. */
+export function validateDecisionRecord(input) {
+    const errors = [];
+    if (!isPlainObject(input)) {
+        return { ok: false, errors: [{ field: "", message: "decision record must be a JSON object" }] };
+    }
+    const schemaVersion = input.schemaVersion;
+    if (schemaVersion !== undefined && schemaVersion !== DECISION_SCHEMA_VERSION) {
+        errors.push({
+            field: "schemaVersion",
+            message: `expected ${DECISION_SCHEMA_VERSION}, got ${String(schemaVersion)}`,
+        });
+    }
+    const decision = input.decision;
+    if (!nonEmptyString(decision)) {
+        errors.push({ field: "decision", message: "required non-empty string" });
+    }
+    let governingRule = null;
+    if (!isPlainObject(input.governingRule) && !nonEmptyString(input.governingRule)) {
+        errors.push({
+            field: "governingRule",
+            message: "required object { description, path?, rfc2119? } or non-empty string",
+        });
+    }
+    else if (nonEmptyString(input.governingRule)) {
+        governingRule = { description: input.governingRule.trim() };
+    }
+    else if (isPlainObject(input.governingRule)) {
+        const gr = input.governingRule;
+        if (!nonEmptyString(gr.description)) {
+            errors.push({ field: "governingRule.description", message: "required non-empty string" });
+        }
+        else {
+            let rfc2119 = null;
+            if (gr.rfc2119 !== undefined && gr.rfc2119 !== null) {
+                if (typeof gr.rfc2119 === "string" && RFC_VALUES.has(gr.rfc2119)) {
+                    rfc2119 = gr.rfc2119;
+                }
+                else {
+                    errors.push({
+                        field: "governingRule.rfc2119",
+                        message: `must be one of ${[...RFC_VALUES].join(", ")}`,
+                    });
+                }
+            }
+            governingRule = {
+                description: gr.description.trim(),
+                path: typeof gr.path === "string" && gr.path.trim().length > 0 ? gr.path.trim() : null,
+                rfc2119,
+            };
+        }
+    }
+    const alternativesRaw = input.alternativesConsidered ?? input.alternatives;
+    const alternatives = [];
+    if (!Array.isArray(alternativesRaw)) {
+        errors.push({
+            field: "alternativesConsidered",
+            message: "required array of { option, whyNot? } or strings",
+        });
+    }
+    else if (alternativesRaw.length === 0) {
+        errors.push({
+            field: "alternativesConsidered",
+            message: 'must include at least one alternative (use [{option:"none"}] if truly sole path)',
+        });
+    }
+    else {
+        for (let i = 0; i < alternativesRaw.length; i += 1) {
+            const alt = alternativesRaw[i];
+            if (nonEmptyString(alt)) {
+                alternatives.push({ option: alt.trim() });
+            }
+            else if (isPlainObject(alt) && nonEmptyString(alt.option)) {
+                alternatives.push({
+                    option: alt.option.trim(),
+                    whyNot: typeof alt.whyNot === "string" && alt.whyNot.trim().length > 0
+                        ? alt.whyNot.trim()
+                        : null,
+                });
+            }
+            else {
+                errors.push({
+                    field: `alternativesConsidered[${i}]`,
+                    message: "must be a non-empty string or { option, whyNot? }",
+                });
+            }
+        }
+    }
+    const whyWinner = input.whyWinner ?? input.why_winner;
+    if (!nonEmptyString(whyWinner)) {
+        errors.push({ field: "whyWinner", message: "required non-empty string" });
+    }
+    const confidenceRaw = input.confidence;
+    let confidence = null;
+    if (!nonEmptyString(confidenceRaw) ||
+        !CONFIDENCE_VALUES.has(confidenceRaw.trim().toLowerCase())) {
+        errors.push({ field: "confidence", message: "required: low | medium | high" });
+    }
+    else {
+        confidence = confidenceRaw.trim().toLowerCase();
+    }
+    const scopeRaw = input.activeScopeRefs ?? input.active_scope_refs ?? input.scopeRefs;
+    const activeScopeRefs = [];
+    if (scopeRaw === undefined || scopeRaw === null) {
+        // optional
+    }
+    else if (Array.isArray(scopeRaw)) {
+        for (let i = 0; i < scopeRaw.length; i += 1) {
+            const s = scopeRaw[i];
+            if (nonEmptyString(s)) {
+                activeScopeRefs.push(s.trim().replace(/\\/g, "/"));
+            }
+            else {
+                errors.push({ field: `activeScopeRefs[${i}]`, message: "must be a non-empty path string" });
+            }
+        }
+    }
+    else if (nonEmptyString(scopeRaw)) {
+        activeScopeRefs.push(scopeRaw.trim().replace(/\\/g, "/"));
+    }
+    else {
+        errors.push({
+            field: "activeScopeRefs",
+            message: "must be a string path, array of paths, or omitted",
+        });
+    }
+    const revisitTrigger = input.revisitTrigger ?? input.revisit_trigger;
+    if (!nonEmptyString(revisitTrigger)) {
+        errors.push({ field: "revisitTrigger", message: "required non-empty string" });
+    }
+    let timestamp = normalizeTimestamp(typeof input.timestamp === "string" ? input.timestamp : null);
+    if (typeof input.timestamp === "string" && input.timestamp.trim().length > 0) {
+        const parsed = new Date(input.timestamp.trim());
+        if (Number.isNaN(parsed.getTime())) {
+            errors.push({ field: "timestamp", message: "invalid ISO-8601 timestamp" });
+        }
+        else {
+            timestamp = normalizeTimestamp(input.timestamp);
+        }
+    }
+    const id = typeof input.id === "string" && input.id.trim().length > 0
+        ? slugifyDecision(input.id)
+        : slugifyDecision(typeof decision === "string" ? decision : "decision");
+    const tags = [];
+    if (Array.isArray(input.tags)) {
+        for (const t of input.tags) {
+            if (nonEmptyString(t))
+                tags.push(t.trim());
+        }
+    }
+    const relatedIssues = [];
+    if (Array.isArray(input.relatedIssues)) {
+        for (const n of input.relatedIssues) {
+            if (typeof n === "number" && Number.isInteger(n) && n > 0)
+                relatedIssues.push(n);
+            else if (typeof n === "string" && /^\d+$/.test(n.trim()))
+                relatedIssues.push(Number(n.trim()));
+        }
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    const record = {
+        schemaVersion: DECISION_SCHEMA_VERSION,
+        id,
+        decision: decision.trim(),
+        governingRule: governingRule,
+        alternativesConsidered: alternatives,
+        whyWinner: whyWinner.trim(),
+        confidence: confidence,
+        activeScopeRefs,
+        timestamp,
+        revisitTrigger: revisitTrigger.trim(),
+        ...(tags.length > 0 ? { tags } : {}),
+        ...(relatedIssues.length > 0 ? { relatedIssues } : {}),
+    };
+    return { ok: true, errors: [], record };
+}
+/** Format validation errors for CLI stderr. */
+export function formatDecisionValidationErrors(errors) {
+    return errors.map((e) => (e.field ? `${e.field}: ${e.message}` : e.message)).join("\n");
+}
+//# sourceMappingURL=schema.js.map

package/dist/decision/write.d.ts

@@ -0,0 +1,82 @@
+/**
+ * decision:write — create a lightweight structured decision record (#1396).
+ */
+import { type DecisionRecord, slugifyDecision } from "./schema.js";
+export type DecisionWriteOutcome = "written" | "error-bad-args" | "error-config" | "error-io";
+export interface DecisionWriteInput {
+    readonly decision?: string;
+    readonly governingRule?: string | {
+        description: string;
+        path?: string;
+        rfc2119?: string;
+    };
+    readonly alternatives?: readonly (string | {
+        option: string;
+        whyNot?: string;
+    })[];
+    readonly whyWinner?: string;
+    readonly confidence?: string;
+    readonly scope?: string | readonly string[];
+    readonly revisitTrigger?: string;
+    readonly id?: string;
+    readonly timestamp?: string;
+    readonly tags?: readonly string[];
+    readonly relatedIssues?: readonly number[];
+    /** Absolute or project-relative path to a JSON body file (full or partial record). */
+    readonly bodyFile?: string;
+    /** Force standalone under xbrief/decisions/ even when --scope is set (still links). */
+    readonly standalone?: boolean;
+    /** When true, replace an existing decision file at the same path. Default: fail if exists. */
+    readonly force?: boolean;
+    readonly projectRoot?: string | null;
+    readonly dryRun?: boolean;
+    readonly json?: boolean;
+}
+export interface DecisionWriteResult {
+    readonly outcome: DecisionWriteOutcome;
+    readonly exitCode: 0 | 1 | 2;
+    readonly path: string | null;
+    readonly scopePath: string | null;
+    readonly record: DecisionRecord | null;
+    readonly message: string;
+}
+/**
+ * Append a pointer line to plan.narratives.Decisions on a scope xBRIEF without
+ * removing existing narratives (validators accept unknown narrative keys as strings).
+ *
+ * Concurrent writers: read-modify-replace with post-write verify + retry so a
+ * later attach does not silently drop an earlier decision pointer.
+ */
+export declare function appendScopeDecisionPointer(projectRoot: string, scopeRelPath: string, decisionRelPath: string, decisionSummary: string): void;
+/** Write a validated decision record to disk (standalone + optional scope pointer). */
+export declare function runDecisionWrite(options: DecisionWriteInput): DecisionWriteResult;
+export interface DecisionWriteCliArgs {
+    decision?: string;
+    governingRule?: string;
+    governingPath?: string;
+    governingRfc?: string;
+    alternatives?: string[];
+    whyWinner?: string;
+    confidence?: string;
+    scope?: string[];
+    revisitTrigger?: string;
+    id?: string;
+    timestamp?: string;
+    tags?: string[];
+    relatedIssues?: number[];
+    bodyFile?: string;
+    standalone?: boolean;
+    force?: boolean;
+    dryRun?: boolean;
+    json?: boolean;
+    projectRoot?: string;
+    error?: string;
+}
+/** Parse argv for decision:write. */
+export declare function parseDecisionWriteArgs(argv: readonly string[]): DecisionWriteCliArgs;
+/** CLI entry for decision:write. */
+export declare function decisionWriteMain(argv: readonly string[]): number;
+/** Relative path helper for tests. */
+export declare function relativeToProject(projectRoot: string, absPath: string): string;
+export { slugifyDecision };
+//# sourceMappingURL=write.d.ts.map