@felixdotgo/aidlc-kit 0.1.1 → 0.3.0

package/dist/src/ledger.js

@@ -1,119 +0,0 @@
-import { createHash, randomUUID } from "node:crypto";
-import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { validateState } from "./state.js";
-export const trackedTasksPath = (root) => join(resolve(root), ".agents/workflow/tasks");
-export const taskEventsPath = (root, taskId) => join(trackedTasksPath(root), taskId, "events");
-const digest = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
-const eventContent = (event) => `${JSON.stringify(event, null, 2)}\n`;
-const eventPath = (root, event) => join(taskEventsPath(root, event.taskId), `${event.id}.json`);
-const taskIdPattern = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
-const iso = (value) => typeof value === "string" && Number.isFinite(Date.parse(value)) && new Date(Date.parse(value)).toISOString() === value;
-const assertSafeTaskId = (taskId) => {
-    if (!taskIdPattern.test(taskId))
-        throw new Error(`Invalid ledger task id: ${taskId}`);
-};
-const atomicWrite = (path, content) => {
-    mkdirSync(dirname(path), { recursive: true });
-    const temporary = `${path}.tmp-${process.pid}-${Date.now()}`;
-    writeFileSync(temporary, content, "utf8");
-    renameSync(temporary, path);
-};
-export const validateLedgerEvent = (value) => {
-    if (!value || typeof value !== "object" || Array.isArray(value))
-        throw new Error("Ledger event must be an object");
-    const event = value;
-    if (event.schemaVersion !== 1 || typeof event.id !== "string" || !taskIdPattern.test(event.id) || typeof event.taskId !== "string" || !taskIdPattern.test(event.taskId) || (event.parentDigest !== null && !/^[a-f0-9]{64}$/.test(event.parentDigest ?? "")) || typeof event.actor !== "string" || !event.actor.trim() || !iso(event.recordedAt) || !event.snapshot || typeof event.digest !== "string" || !/^[a-f0-9]{64}$/.test(event.digest))
-        throw new Error("Invalid ledger event fields");
-    if (event.snapshot.id !== event.taskId)
-        throw new Error(`Ledger event task mismatch: ${event.id}`);
-    validateState({ schemaVersion: 4, tasks: { [event.taskId]: event.snapshot }, archive: {} });
-    const { digest: supplied, ...unsigned } = event;
-    if (digest(unsigned) !== supplied)
-        throw new Error(`Ledger event digest mismatch: ${event.id}`);
-    return event;
-};
-export const createLedgerEvent = (task, parentDigest, actor, recordedAt = new Date().toISOString(), id = randomUUID()) => {
-    assertSafeTaskId(task.id);
-    if (!actor.trim() || !iso(recordedAt) || !taskIdPattern.test(id))
-        throw new Error("Invalid ledger event metadata");
-    validateState({ schemaVersion: 4, tasks: { [task.id]: task }, archive: {} });
-    const unsigned = { schemaVersion: 1, id, taskId: task.id, parentDigest, actor, recordedAt, snapshot: task };
-    return { ...unsigned, digest: digest(unsigned) };
-};
-export const loadTaskLedger = (root, taskId) => {
-    assertSafeTaskId(taskId);
-    const directory = taskEventsPath(root, taskId);
-    if (!existsSync(directory))
-        return [];
-    if (lstatSync(directory).isSymbolicLink())
-        throw new Error(`Ledger path crosses a symlink: ${taskId}`);
-    const events = readdirSync(directory, { withFileTypes: true })
-        .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
-        .map((entry) => validateLedgerEvent(JSON.parse(readFileSync(join(directory, entry.name), "utf8"))))
-        .sort((left, right) => left.id.localeCompare(right.id));
-    if (events.some((event) => event.taskId !== taskId))
-        throw new Error(`Ledger event is in the wrong task directory: ${taskId}`);
-    return events;
-};
-export const reduceTaskLedger = (events) => {
-    if (!events.length)
-        return undefined;
-    const byDigest = new Map(events.map((event) => [event.digest, event]));
-    if (byDigest.size !== events.length)
-        throw new Error("Duplicate ledger event digest");
-    const roots = events.filter((event) => event.parentDigest === null);
-    if (roots.length !== 1)
-        throw new Error("Ledger must have exactly one root event");
-    const children = new Map();
-    for (const event of events)
-        if (event.parentDigest) {
-            if (!byDigest.has(event.parentDigest))
-                throw new Error(`Ledger event has unknown parent: ${event.id}`);
-            const siblings = children.get(event.parentDigest) ?? [];
-            siblings.push(event);
-            children.set(event.parentDigest, siblings);
-        }
-    const sibling = [...children.values()].find((items) => items.length > 1);
-    if (sibling)
-        throw new Error(`Concurrent ledger events require resolution: ${sibling.map((event) => event.id).join(", ")}`);
-    const visited = new Set();
-    let current = roots[0];
-    while (true) {
-        if (visited.has(current.digest))
-            throw new Error("Ledger event cycle");
-        visited.add(current.digest);
-        const next = children.get(current.digest) ?? [];
-        if (!next.length)
-            break;
-        current = next[0];
-    }
-    if (visited.size !== events.length)
-        throw new Error("Ledger contains disconnected events");
-    return { task: current.snapshot, headDigest: current.digest };
-};
-export const loadTrackedState = (root) => {
-    const directory = trackedTasksPath(root);
-    if (!existsSync(directory))
-        return undefined;
-    if (lstatSync(directory).isSymbolicLink())
-        throw new Error("Tracked ledger path crosses a symlink");
-    const tasks = {};
-    for (const entry of readdirSync(directory, { withFileTypes: true })) {
-        if (!entry.isDirectory() || !taskIdPattern.test(entry.name))
-            continue;
-        const reduced = reduceTaskLedger(loadTaskLedger(root, entry.name));
-        if (reduced)
-            tasks[entry.name] = reduced.task;
-    }
-    return validateState({ schemaVersion: 4, tasks, archive: {} });
-};
-export const appendTaskLedgerEvent = (root, task, actor) => {
-    const current = reduceTaskLedger(loadTaskLedger(root, task.id));
-    const event = createLedgerEvent(task, current?.headDigest ?? null, actor);
-    const path = eventPath(root, event);
-    if (existsSync(path))
-        throw new Error(`Ledger event already exists: ${event.id}`);
-    atomicWrite(path, eventContent(event));
-    return event;
-};

package/dist/src/state/shared.d.ts

@@ -1,29 +0,0 @@
-import type { ArchivedTaskSummary, Gate, HandoffKind, Phase, TaskState, WorkflowState } from "../model.js";
-export declare const statePath: (root: string) => string;
-export declare const lessonIndexPath: (root: string) => string;
-export declare const memoryRegistryPath: (root: string) => string;
-export declare const stateLockPath: (root: string) => string;
-export declare const stateLockGuardPath: (root: string) => string;
-export declare const emptyState: () => WorkflowState;
-export declare const legacyG2WaitSource = "schema-v4-migration";
-export declare const phases: Phase[];
-export declare const gates: Gate[];
-export declare const handoffKinds: HandoffKind[];
-export declare const terminal: (task: TaskState) => boolean;
-export declare const phaseGate: (phase: Phase) => Gate;
-export declare const iso: (value: unknown) => value is string;
-export declare const text: (value: unknown) => value is string;
-export declare const idPattern: RegExp;
-export declare const digest: (content: string) => string;
-export declare const archiveRecordPath: (id: string) => string;
-export declare const taskRecordContent: (task: TaskState) => string;
-export declare const assertNoSymlinkPath: (root: string, relative: string) => void;
-export declare const writeAtomic: (path: string, content: string) => void;
-export declare const parseJsonText: (content: string, label: string, recovery?: string) => unknown;
-export declare const parseJsonFile: (path: string, label: string, recovery?: string) => unknown;
-export declare const audited: (reason: string, source: string) => void;
-export declare const tokens: (value: string) => string[];
-/** Rejects artifact paths that escape the project-owned tasks directory. */
-export declare const assertTaskArtifactPath: (id: string, path: string) => void;
-/** Builds the immutable archive-catalog summary for a terminal task from its record content. */
-export declare const archivedSummary: (task: TaskState, content?: string) => ArchivedTaskSummary;

package/dist/src/state/shared.js

@@ -1,71 +0,0 @@
-import { createHash } from "node:crypto";
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { dirname, isAbsolute, join, normalize, resolve } from "node:path";
-import { resolveProjectPathWithoutSymlinks } from "../project-path.js";
-export const statePath = (root) => join(resolve(root), ".agents/data/state/aidlc-state.json");
-export const lessonIndexPath = (root) => join(resolve(root), ".agents/data/lessons/index.json");
-export const memoryRegistryPath = (root) => join(resolve(root), ".agents/data/memory/agentic-memory.json");
-export const stateLockPath = (root) => join(resolve(root), ".agents/data/state/.aidlc-state.lock");
-export const stateLockGuardPath = (root) => join(resolve(root), ".agents/data/state/.aidlc-state.lock.guard");
-export const emptyState = () => ({ schemaVersion: 4, tasks: {}, archive: {} });
-export const legacyG2WaitSource = "schema-v4-migration";
-export const phases = ["clarify", "plan", "build", "wrap", "done"];
-export const gates = ["none", "G0_confirm", "G1_review", "G2_codereview"];
-export const handoffKinds = ["repair_exhausted", "review_exhausted", "g2_failed", "release_failed", "structural_change", "other"];
-export const terminal = (task) => task.status === "done" || task.status === "closed" || task.status === "superseded";
-export const phaseGate = (phase) => phase === "clarify" ? "G0_confirm" : phase === "plan" ? "G1_review" : phase === "build" ? "G2_codereview" : "none";
-export const iso = (value) => typeof value === "string" && Number.isFinite(Date.parse(value)) && new Date(Date.parse(value)).toISOString() === value;
-export const text = (value) => typeof value === "string" && Boolean(value.trim());
-export const idPattern = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
-export const digest = (content) => createHash("sha256").update(content).digest("hex");
-export const archiveRecordPath = (id) => `.agents/data/state/archive/${id}.json`;
-export const taskRecordContent = (task) => `${JSON.stringify(task, null, 2)}\n`;
-export const assertNoSymlinkPath = (root, relative) => {
-    resolveProjectPathWithoutSymlinks(root, relative, "Unsafe state path", "State path crosses a symlink");
-};
-export const writeAtomic = (path, content) => {
-    mkdirSync(dirname(path), { recursive: true });
-    const temporary = `${path}.tmp-${process.pid}-${Date.now()}`;
-    writeFileSync(temporary, content, "utf8");
-    renameSync(temporary, path);
-};
-export const parseJsonText = (content, label, recovery = "") => {
-    try {
-        return JSON.parse(content);
-    }
-    catch (error) {
-        throw new Error(`${label} is corrupted or unreadable: ${error instanceof Error ? error.message : String(error)}${recovery ? `; ${recovery}` : ""}`);
-    }
-};
-export const parseJsonFile = (path, label, recovery = "") => parseJsonText(readFileSync(path, "utf8"), label, recovery);
-export const audited = (reason, source) => {
-    if (!text(reason) || !text(source))
-        throw new Error("Lifecycle mutation requires non-empty --reason and --source");
-};
-export const tokens = (value) => [...new Set(value.toLocaleLowerCase().split(/[^\p{L}\p{N}]+/u).filter((item) => item.length > 1))];
-/** Rejects artifact paths that escape the project-owned tasks directory. */
-export const assertTaskArtifactPath = (id, path) => {
-    const separator = process.platform === "win32" ? "\\" : "/";
-    const cleaned = normalize(path);
-    if (isAbsolute(cleaned) || cleaned === ".." || cleaned.startsWith(`..${separator}`) || !cleaned.startsWith(`.agents${separator}data${separator}tasks${separator}`)) {
-        throw new Error(`Invalid artifact path for ${id}: ${path}`);
-    }
-};
-/** Builds the immutable archive-catalog summary for a terminal task from its record content. */
-export const archivedSummary = (task, content = taskRecordContent(task)) => ({
-    id: task.id,
-    title: task.title,
-    type: task.type,
-    phase: task.phase,
-    gate: task.gate,
-    status: task.status,
-    risk: task.risk,
-    areas: task.areas,
-    record: archiveRecordPath(task.id),
-    digest: digest(content),
-    lessonCount: task.lessons?.length ?? 0,
-    predecessorTaskId: task.predecessorTaskId,
-    successorTaskId: task.successorTaskId,
-    createdAt: task.createdAt,
-    updatedAt: task.updatedAt
-});

package/dist/src/tracker.d.ts

@@ -1,36 +0,0 @@
-/**
- * Backlog tracker integration: resolves tracker credentials from the environment
- * and builds the HTTP requests used to mirror lifecycle phase transitions.
- */
-import type { TrackerConfig } from "./model.js";
-export interface TrackerDiagnostic {
-    code: "TRACKER_DISABLED" | "TRACKER_AUTH" | "TRACKER_RATE_LIMIT" | "TRACKER_REQUEST";
-    message: string;
-    retryable: boolean;
-}
-export interface BacklogRequest {
-    method: "GET" | "PATCH";
-    path: string;
-    form?: Record<string, string | number>;
-}
-export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
-export type TrackerResolution = {
-    enabled: false;
-    diagnostic: TrackerDiagnostic;
-} | {
-    enabled: true;
-    config: TrackerConfig;
-    token: string;
-};
-/** Resolves a tracker configuration into either an enabled resolution (with token) or a disabled diagnostic. */
-export declare const resolveTracker: (config: TrackerConfig | undefined, environment?: NodeJS.ProcessEnv) => TrackerResolution;
-/** Executes a single Backlog request, mapping HTTP failures to retryable diagnostics. */
-export declare const executeBacklog: (resolution: TrackerResolution, request: BacklogRequest, fetcher?: FetchLike) => Promise<{
-    ok: true;
-    body: unknown;
-} | {
-    ok: false;
-    diagnostic: TrackerDiagnostic;
-}>;
-/** Builds the Backlog PATCH request that mirrors a lifecycle phase transition for an issue. */
-export declare const gateUpdate: (config: TrackerConfig, issue: string, phase: "clarify" | "plan" | "build" | "wrap" | "done", idempotencyKey: string) => BacklogRequest;

package/dist/src/tracker.js

@@ -1,44 +0,0 @@
-/** Resolves a tracker configuration into either an enabled resolution (with token) or a disabled diagnostic. */
-export const resolveTracker = (config, environment = process.env) => {
-    if (!config)
-        return { enabled: false, diagnostic: { code: "TRACKER_DISABLED", message: "Tracker is not configured; Git-only mode is active.", retryable: false } };
-    const token = environment[config.tokenEnv];
-    if (!token)
-        return { enabled: false, diagnostic: { code: "TRACKER_DISABLED", message: `Backlog tracker is disabled because ${config.tokenEnv} is unavailable.`, retryable: false } };
-    return { enabled: true, config, token };
-};
-const form = (values) => {
-    const body = new URLSearchParams();
-    for (const [key, value] of Object.entries(values))
-        body.set(key, String(value));
-    return body;
-};
-/** Executes a single Backlog request, mapping HTTP failures to retryable diagnostics. */
-export const executeBacklog = async (resolution, request, fetcher = fetch) => {
-    if (!resolution.enabled)
-        return { ok: false, diagnostic: resolution.diagnostic };
-    const response = await fetcher(`${resolution.config.spaceUrl}/api/v2/${request.path.replace(/^\//, "")}`, {
-        method: request.method,
-        headers: { Authorization: `Bearer ${resolution.token}`, ...(request.form ? { "Content-Type": "application/x-www-form-urlencoded" } : {}) },
-        body: request.form ? form(request.form) : undefined
-    });
-    if (response.status === 401)
-        return { ok: false, diagnostic: { code: "TRACKER_AUTH", message: "Backlog authentication failed; Git state was not changed.", retryable: false } };
-    if (response.status === 429)
-        return { ok: false, diagnostic: { code: "TRACKER_RATE_LIMIT", message: "Backlog rate limit reached; retry after the provider reset window.", retryable: true } };
-    if (!response.ok)
-        return { ok: false, diagnostic: { code: "TRACKER_REQUEST", message: `Backlog request failed with HTTP ${response.status}.`, retryable: response.status >= 500 } };
-    return { ok: true, body: await response.json() };
-};
-/** Builds the Backlog PATCH request that mirrors a lifecycle phase transition for an issue. */
-export const gateUpdate = (config, issue, phase, idempotencyKey) => {
-    const comment = `[aidlc:${idempotencyKey}] ${phase}`;
-    if (config.workflow === "waterfall") {
-        const statusId = config.mapping.statuses?.[phase];
-        if (!statusId)
-            throw new Error(`Backlog status mapping is required for Waterfall phase: ${phase}`);
-        return { method: "PATCH", path: `issues/${issue}`, form: { statusId, comment } };
-    }
-    const field = config.mapping.gateFieldId;
-    return { method: "PATCH", path: `issues/${issue}`, form: { ...(field ? { [`customField_${field}`]: phase } : {}), comment } };
-};