@dsalazardev/ai-hub-cli 0.0.0-stage → 0.2.0

package/dist/harness/guards/index.d.ts

@@ -0,0 +1,6 @@
+export * from './types.js';
+export * from './danger.js';
+export * from './branch.js';
+export * from './trunk.js';
+export * from './ship.js';
+export * from './preflight.js';

package/dist/harness/guards/index.js

@@ -0,0 +1,6 @@
+export * from './types.js';
+export * from './danger.js';
+export * from './branch.js';
+export * from './trunk.js';
+export * from './ship.js';
+export * from './preflight.js';

package/dist/harness/guards/preflight.d.ts

@@ -0,0 +1,14 @@
+import { type GuardContext, type GuardMode, type GuardResult } from './types.js';
+export declare const GUARD_RULE_IDS: string[];
+/**
+ * Pure policy evaluation. All IO (git, filesystem, config) belongs to the caller
+ * that builds GuardContext. No imports from node:fs, node:child_process or node:net.
+ */
+export declare function runPreflight(command: string, ctx: GuardContext): GuardResult;
+export interface PreflightOutcome {
+    result: GuardResult;
+    mode: GuardMode;
+    blocked: boolean;
+}
+export declare function evaluatePreflight(command: string, ctx: GuardContext, mode?: GuardMode): PreflightOutcome;
+export declare function requiresConfirmation(result: GuardResult): boolean;

package/dist/harness/guards/preflight.js

@@ -0,0 +1,37 @@
+import { classifyBranch } from './branch.js';
+import { classifyDanger, DANGER_RULE_IDS } from './danger.js';
+import { classifyShip } from './ship.js';
+import { classifyTrunk } from './trunk.js';
+import { ALLOW_RULE } from './types.js';
+export const GUARD_RULE_IDS = [
+    ...DANGER_RULE_IDS,
+    'ship:unpushed',
+    'trunk:closed',
+    'branch:checked-out-elsewhere',
+    ALLOW_RULE,
+];
+/**
+ * Pure policy evaluation. All IO (git, filesystem, config) belongs to the caller
+ * that builds GuardContext. No imports from node:fs, node:child_process or node:net.
+ */
+export function runPreflight(command, ctx) {
+    return (classifyDanger(command, ctx.preset?.dangerPatterns ?? []) ??
+        classifyShip(command, ctx) ??
+        classifyTrunk(command, ctx) ??
+        classifyBranch(command, ctx) ?? {
+        decision: 'allow',
+        rule: ALLOW_RULE,
+        reason: 'sin reglas de peligro, trunk o rama aplicables.',
+    });
+}
+export function evaluatePreflight(command, ctx, mode = ctx.policy.guardMode) {
+    const result = runPreflight(command, ctx);
+    return {
+        result,
+        mode,
+        blocked: mode === 'enforce' && result.decision !== 'allow',
+    };
+}
+export function requiresConfirmation(result) {
+    return result.decision === 'ask';
+}

package/dist/harness/guards/ship.d.ts

@@ -0,0 +1,2 @@
+import type { GuardContext, GuardResult } from './types.js';
+export declare function classifyShip(command: string, ctx: GuardContext): GuardResult | null;

package/dist/harness/guards/ship.js

@@ -0,0 +1,35 @@
+import { branchSwitchTarget } from './branch.js';
+import { isTrunkBranch } from './trunk.js';
+function movesIntoTrunk(command, ctx) {
+    const cleaned = command.replace(/\s+/g, ' ').trim();
+    const isTrunk = (branch) => isTrunkBranch(branch) || branch === ctx.git.defaultBranch;
+    const switched = branchSwitchTarget(cleaned);
+    if (switched !== null && isTrunk(switched)) {
+        return true;
+    }
+    const merge = /\bgit\s+merge\s+([^\s;|&]+)/i.exec(cleaned);
+    if (merge && isTrunk(merge[1])) {
+        return true;
+    }
+    return isTrunk(ctx.git.branch) && /\bgit\s+merge\b/i.test(cleaned);
+}
+export function classifyShip(command, ctx) {
+    if (!movesIntoTrunk(command, ctx)) {
+        return null;
+    }
+    const pending = [];
+    if (ctx.git.dirty) {
+        pending.push('cambios sin commit');
+    }
+    if (ctx.git.ahead > 0) {
+        pending.push(`${ctx.git.ahead} commit(s) sin push`);
+    }
+    if (pending.length === 0) {
+        return null;
+    }
+    return {
+        decision: 'deny',
+        rule: 'ship:unpushed',
+        reason: `no muevas trabajo sin publicar a la trunk (${pending.join(', ')}); haz commit, push y abre una PR, o guarda el trabajo en una rama antes de continuar.`,
+    };
+}

package/dist/harness/guards/trunk.d.ts

@@ -0,0 +1,5 @@
+import type { GuardContext, GuardResult } from './types.js';
+export declare const TRUNK_BRANCHES: Set<string>;
+export declare function isTrunkBranch(branch: string): boolean;
+export declare function trunkIsClosed(ctx: GuardContext): boolean;
+export declare function classifyTrunk(command: string, ctx: GuardContext): GuardResult | null;

package/dist/harness/guards/trunk.js

@@ -0,0 +1,41 @@
+export const TRUNK_BRANCHES = new Set(['main', 'master', 'trunk']);
+export function isTrunkBranch(branch) {
+    return TRUNK_BRANCHES.has(branch.toLowerCase());
+}
+function writesToCheckedOutTrunk(command) {
+    const cleaned = command.replace(/\s+/g, ' ').trim();
+    return (/\bgit\s+commit\b/i.test(cleaned) ||
+        /\bgit\s+merge\b/i.test(cleaned) ||
+        /\bgit\s+rebase\b/i.test(cleaned) ||
+        /\bgit\s+push\b/i.test(cleaned) ||
+        /\bgit\s+tag\b/i.test(cleaned));
+}
+export function trunkIsClosed(ctx) {
+    if (ctx.policy.optOuts.includes('trunk')) {
+        return false;
+    }
+    if (ctx.policy.trunk === 'open') {
+        return false;
+    }
+    if (ctx.policy.trunk === 'closed') {
+        return true;
+    }
+    return ctx.project.hasCI || ctx.project.hasDeploy || ctx.project.team;
+}
+export function classifyTrunk(command, ctx) {
+    if (!writesToCheckedOutTrunk(command)) {
+        return null;
+    }
+    const onTrunk = isTrunkBranch(ctx.git.branch) || ctx.git.branch === ctx.git.defaultBranch;
+    if (!onTrunk) {
+        return null;
+    }
+    if (!trunkIsClosed(ctx)) {
+        return null;
+    }
+    return {
+        decision: 'deny',
+        rule: 'trunk:closed',
+        reason: 'the trunk is closed by CI, deployment, team signals or project policy; create a branch (git switch -c feat/<topic>), commit there and open a PR.',
+    };
+}

package/dist/harness/guards/types.d.ts

@@ -0,0 +1,50 @@
+export type GuardDecision = 'allow' | 'ask' | 'deny' | 'block';
+export type GuardMode = 'shadow' | 'enforce';
+export interface WorktreeInfo {
+    path: string;
+    branch: string;
+    dirty: boolean;
+    owned: boolean;
+}
+export interface PresetDangerPattern {
+    id: string;
+    pattern: string;
+    decision: 'ask' | 'deny';
+    reason: string;
+}
+export interface GuardContext {
+    root: string;
+    git: {
+        branch: string;
+        defaultBranch: string;
+        head: string;
+        dirty: boolean;
+        ahead: number;
+        worktrees: WorktreeInfo[];
+    };
+    project: {
+        preset: string;
+        languages: string[];
+        hasCI: boolean;
+        hasDeploy: boolean;
+        team: boolean;
+    };
+    session?: {
+        id: string;
+        checkout: string;
+    };
+    policy: {
+        trunk: 'auto' | 'closed' | 'open';
+        guardMode: GuardMode;
+        optOuts: string[];
+    };
+    preset?: {
+        dangerPatterns: PresetDangerPattern[];
+    };
+}
+export interface GuardResult {
+    decision: GuardDecision;
+    rule: string;
+    reason: string;
+}
+export declare const ALLOW_RULE = "preflight:allow";

package/dist/harness/guards/types.js

@@ -0,0 +1 @@
+export const ALLOW_RULE = 'preflight:allow';

package/dist/harness/memory/ledger.d.ts

@@ -0,0 +1,53 @@
+import { type ProjectState } from './state.js';
+export declare const LEDGER_RELATIVE = ".planning/memory.jsonl";
+export declare const LEDGER_SCHEMA_VERSION = 1;
+export declare const DEFAULT_RETENTION = 1000;
+export declare const LEDGER_EVENTS: readonly ["start", "checkpoint", "decision", "end"];
+export type LedgerEventName = (typeof LEDGER_EVENTS)[number];
+export interface LedgerDecision {
+    id: string;
+    choice: string;
+    alternatives: string[];
+}
+export interface LedgerEvent {
+    schemaVersion: 1;
+    sessionId: string;
+    changeId: string | null;
+    event: LedgerEventName;
+    branch: string | null;
+    worktree: string | null;
+    baselineHead: string | null;
+    head: string | null;
+    files: string[];
+    commits: string[];
+    toolCalls: number;
+    decision?: LedgerDecision;
+    timestamps: {
+        at: string;
+    };
+}
+export declare class LedgerValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Closed schema: only the fields below survive. Prompts, responses, file
+ * contents and secrets are dropped even if the caller sends them.
+ */
+export declare function sanitizeEvent(input: Record<string, unknown>, now?: Date): LedgerEvent;
+export declare function readLedger(root: string, limit?: number): Promise<LedgerEvent[]>;
+export declare function appendLedger(root: string, input: Record<string, unknown>, retention?: number): Promise<LedgerEvent>;
+export declare function queryLedger(events: LedgerEvent[], filter: {
+    changeId?: string;
+    sessionId?: string;
+}): LedgerEvent[];
+export interface ResumeSummary {
+    last: LedgerEvent | null;
+    activeChange: string | null;
+    phase: string;
+    tasks: {
+        total: number;
+        done: number;
+    };
+    state: ProjectState | null;
+}
+export declare function resumeLedger(root: string): Promise<ResumeSummary>;

package/dist/harness/memory/ledger.js

@@ -0,0 +1,136 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { readState, StateNotFoundError } from './state.js';
+export const LEDGER_RELATIVE = '.planning/memory.jsonl';
+export const LEDGER_SCHEMA_VERSION = 1;
+export const DEFAULT_RETENTION = 1000;
+export const LEDGER_EVENTS = ['start', 'checkpoint', 'decision', 'end'];
+export class LedgerValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'LedgerValidationError';
+    }
+}
+function text(value, field) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    if (typeof value !== 'string') {
+        throw new LedgerValidationError(`"${field}" debe ser texto`);
+    }
+    return value.length > 500 ? value.slice(0, 500) : value;
+}
+function list(value, field) {
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (!Array.isArray(value) || !value.every((item) => typeof item === 'string')) {
+        throw new LedgerValidationError(`"${field}" debe ser una lista de textos`);
+    }
+    return value.slice(0, 200);
+}
+function decision(value) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (typeof value !== 'object' || Array.isArray(value)) {
+        throw new LedgerValidationError('"decision" debe ser un objeto');
+    }
+    const data = value;
+    const id = text(data.id, 'decision.id');
+    const choice = text(data.choice, 'decision.choice');
+    if (!id || !choice) {
+        throw new LedgerValidationError('"decision.id" y "decision.choice" son obligatorios');
+    }
+    return { id, choice, alternatives: list(data.alternatives, 'decision.alternatives') };
+}
+/**
+ * Closed schema: only the fields below survive. Prompts, responses, file
+ * contents and secrets are dropped even if the caller sends them.
+ */
+export function sanitizeEvent(input, now = new Date()) {
+    const sessionId = text(input.sessionId, 'sessionId');
+    if (!sessionId) {
+        throw new LedgerValidationError('"sessionId" es obligatorio');
+    }
+    const event = input.event ?? 'checkpoint';
+    if (typeof event !== 'string' || !LEDGER_EVENTS.includes(event)) {
+        throw new LedgerValidationError(`"event" debe ser uno de: ${LEDGER_EVENTS.join(', ')}`);
+    }
+    const toolCalls = input.toolCalls ?? 0;
+    if (typeof toolCalls !== 'number' || !Number.isFinite(toolCalls) || toolCalls < 0) {
+        throw new LedgerValidationError('"toolCalls" debe ser un número no negativo');
+    }
+    const base = {
+        schemaVersion: LEDGER_SCHEMA_VERSION,
+        sessionId,
+        changeId: text(input.changeId, 'changeId'),
+        event: event,
+        branch: text(input.branch, 'branch'),
+        worktree: text(input.worktree, 'worktree'),
+        baselineHead: text(input.baselineHead, 'baselineHead'),
+        head: text(input.head, 'head'),
+        files: list(input.files, 'files'),
+        commits: list(input.commits, 'commits'),
+        toolCalls: Math.trunc(toolCalls),
+        timestamps: { at: now.toISOString() },
+    };
+    const decided = decision(input.decision);
+    if (decided) {
+        base.decision = decided;
+    }
+    return base;
+}
+function ledgerPath(root) {
+    return path.join(root, LEDGER_RELATIVE);
+}
+export async function readLedger(root, limit) {
+    const raw = await fs.readFile(ledgerPath(root), 'utf8').catch(() => '');
+    const events = [];
+    for (const line of raw.split('\n')) {
+        if (line.trim() === '') {
+            continue;
+        }
+        try {
+            events.push(JSON.parse(line));
+        }
+        catch {
+            continue;
+        }
+    }
+    return limit === undefined ? events : events.slice(-limit);
+}
+export async function appendLedger(root, input, retention = DEFAULT_RETENTION) {
+    const event = sanitizeEvent(input);
+    const file = ledgerPath(root);
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    const existing = await readLedger(root);
+    const next = [...existing, event];
+    const kept = next.length > retention ? next.slice(-retention) : next;
+    await fs.writeFile(file, `${kept.map((item) => JSON.stringify(item)).join('\n')}\n`, 'utf8');
+    return event;
+}
+export function queryLedger(events, filter) {
+    return events.filter((event) => (filter.changeId === undefined || event.changeId === filter.changeId) &&
+        (filter.sessionId === undefined || event.sessionId === filter.sessionId));
+}
+export async function resumeLedger(root) {
+    const events = await readLedger(root, 1);
+    const last = events.length > 0 ? events[events.length - 1] : null;
+    let state = null;
+    try {
+        state = await readState(root);
+    }
+    catch (error) {
+        if (!(error instanceof StateNotFoundError)) {
+            throw error;
+        }
+    }
+    return {
+        last,
+        activeChange: state?.activeChange ?? null,
+        phase: state?.phase ?? 'idle',
+        tasks: state?.tasks ?? { total: 0, done: 0 },
+        state,
+    };
+}

package/dist/harness/memory/state.d.ts

@@ -0,0 +1,35 @@
+export declare const STATE_RELATIVE = ".planning/state.json";
+export declare const LEGACY_PATHS_FILE: string;
+export type Lane = 'assessment' | 'feature' | 'bug';
+export interface ProjectState {
+    version: 1;
+    project: string;
+    preset: string;
+    activeChange: string | null;
+    lane: Lane | null;
+    phase: string;
+    tasks: {
+        total: number;
+        done: number;
+    };
+    branch: string | null;
+    worktree: string | null;
+    updatedAt: string;
+}
+export declare class StateNotFoundError extends Error {
+    constructor(statePath: string);
+}
+export declare class StateSchemaError extends Error {
+    readonly validationErrors: string[];
+    constructor(errors: string[]);
+}
+export declare function emptyState(project: string, preset: string): ProjectState;
+export declare function statePath(root: string): string;
+export declare function readState(root: string): Promise<ProjectState>;
+export declare function writeState(root: string, state: ProjectState): Promise<void>;
+export interface LegacyStatePaths {
+    state: string;
+    changes: string;
+}
+export declare function legacyStatePaths(): Promise<LegacyStatePaths>;
+export declare function migrateLegacyState(root: string, project: string, preset: string): Promise<ProjectState | null>;

package/dist/harness/memory/state.js

@@ -0,0 +1,121 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Ajv } from 'ajv';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SCHEMA_PATH = path.join(__dirname, '..', '..', '..', 'schema', 'state.schema.json');
+export const STATE_RELATIVE = '.planning/state.json';
+export const LEGACY_PATHS_FILE = path.join(__dirname, '..', '..', '..', 'engine', 'legacy-paths.json');
+export class StateNotFoundError extends Error {
+    constructor(statePath) {
+        super(`state.json no encontrado: ${statePath}. Ejecuta ai-hub init`);
+        this.name = 'StateNotFoundError';
+    }
+}
+export class StateSchemaError extends Error {
+    validationErrors;
+    constructor(errors) {
+        super(`state.json no es válido:\n${errors.join('\n')}`);
+        this.name = 'StateSchemaError';
+        this.validationErrors = errors;
+    }
+}
+let validateFn = null;
+async function validator() {
+    if (validateFn) {
+        return validateFn;
+    }
+    const schema = JSON.parse(await fs.readFile(SCHEMA_PATH, 'utf8'));
+    const ajv = new Ajv({ allErrors: true });
+    validateFn = ajv.compile(schema);
+    return validateFn;
+}
+function describe(errors) {
+    return (errors ?? []).map((error) => `${error.instancePath || '(root)'} ${error.message ?? 'inválido'}`);
+}
+export function emptyState(project, preset) {
+    return {
+        version: 1,
+        project,
+        preset,
+        activeChange: null,
+        lane: null,
+        phase: 'idle',
+        tasks: { total: 0, done: 0 },
+        branch: null,
+        worktree: null,
+        updatedAt: new Date().toISOString(),
+    };
+}
+export function statePath(root) {
+    return path.join(root, STATE_RELATIVE);
+}
+export async function readState(root) {
+    const file = statePath(root);
+    const raw = await fs.readFile(file, 'utf8').catch(() => {
+        throw new StateNotFoundError(file);
+    });
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new StateSchemaError([`(root) JSON inválido: ${error.message}`]);
+    }
+    const validate = await validator();
+    if (!validate(data)) {
+        throw new StateSchemaError(describe(validate.errors));
+    }
+    return data;
+}
+export async function writeState(root, state) {
+    const validate = await validator();
+    const next = { ...state, updatedAt: new Date().toISOString() };
+    if (!validate(next)) {
+        throw new StateSchemaError(describe(validate.errors));
+    }
+    const file = statePath(root);
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+}
+export async function legacyStatePaths() {
+    const raw = await fs.readFile(LEGACY_PATHS_FILE, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.state !== 'string' || typeof parsed.changes !== 'string') {
+        throw new StateSchemaError(['legacy-paths.json no declara "state" y "changes"']);
+    }
+    return { state: parsed.state, changes: parsed.changes };
+}
+export async function migrateLegacyState(root, project, preset) {
+    const paths = await legacyStatePaths();
+    const raw = await fs.readFile(path.join(root, paths.state), 'utf8').catch(() => null);
+    if (raw === null) {
+        return null;
+    }
+    let legacy;
+    try {
+        legacy = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    const activeChange = typeof legacy.active_change === 'string' ? legacy.active_change : null;
+    const changes = Array.isArray(legacy.changes) ? legacy.changes : [];
+    const active = activeChange ? changes.find((change) => change.name === activeChange) : null;
+    const phase = active && typeof active.phase === 'string' ? active.phase : activeChange ? 'in-progress' : 'idle';
+    let total = 0;
+    let done = 0;
+    if (activeChange) {
+        const tasks = await fs.readFile(path.join(root, paths.changes, activeChange, 'tasks.md'), 'utf8').catch(() => '');
+        total = tasks.split('\n').filter((line) => /^\s*-\s*\[[ x]\]/.test(line)).length;
+        done = tasks.split('\n').filter((line) => /^\s*-\s*\[x\]/.test(line)).length;
+    }
+    const migrated = {
+        ...emptyState(project, preset),
+        activeChange,
+        phase,
+        tasks: { total, done },
+    };
+    await writeState(root, migrated);
+    return migrated;
+}

package/dist/harness/worktree/reaper.d.ts

@@ -0,0 +1,32 @@
+export interface WorktreeFacts {
+    path: string;
+    branch: string;
+    owned: boolean;
+    dirty: boolean;
+    untrackedNonRegenerable: boolean;
+    unmergedCommits: number;
+    integrated: boolean;
+}
+export type ReapDecision = 'keep' | 'ask' | 'remove';
+export interface ReapPlan {
+    path: string;
+    branch: string;
+    decision: ReapDecision;
+    rule: string;
+    reason: string;
+}
+export interface ReapOptions {
+    confirm: boolean;
+}
+/**
+ * Three conservative questions, each failing towards keeping:
+ * provenance (did ai-hub create it?), integration (is the branch landed?),
+ * contents (are there non-regenerable files?).
+ */
+export declare function decideWorktree(facts: WorktreeFacts, options: ReapOptions): ReapPlan;
+export interface ReapReport {
+    keep: ReapPlan[];
+    ask: ReapPlan[];
+    remove: ReapPlan[];
+}
+export declare function planReap(worktrees: WorktreeFacts[], options: ReapOptions): ReapReport;

package/dist/harness/worktree/reaper.js

@@ -0,0 +1,54 @@
+/**
+ * Three conservative questions, each failing towards keeping:
+ * provenance (did ai-hub create it?), integration (is the branch landed?),
+ * contents (are there non-regenerable files?).
+ */
+export function decideWorktree(facts, options) {
+    const base = { path: facts.path, branch: facts.branch };
+    if (!facts.owned) {
+        return {
+            ...base,
+            decision: 'keep',
+            rule: 'reaper:foreign',
+            reason: 'el worktree no fue creado por ai-hub; no se toca.',
+        };
+    }
+    if (!facts.integrated || facts.unmergedCommits > 0) {
+        return {
+            ...base,
+            decision: 'keep',
+            rule: 'reaper:unmerged',
+            reason: `la rama tiene ${facts.unmergedCommits} commit(s) sin integrar en la trunk; intégrala o abre una PR antes de reapear.`,
+        };
+    }
+    if (facts.dirty || facts.untrackedNonRegenerable) {
+        return {
+            ...base,
+            decision: 'keep',
+            rule: 'reaper:contents',
+            reason: 'hay cambios sin commit o archivos no regenerables; guarda el trabajo o muévelo a una rama antes de reapear.',
+        };
+    }
+    if (!options.confirm) {
+        return {
+            ...base,
+            decision: 'ask',
+            rule: 'reaper:clean-owned',
+            reason: 'worktree limpio y propio; se elimina solo con --confirm.',
+        };
+    }
+    return {
+        ...base,
+        decision: 'remove',
+        rule: 'reaper:clean-owned',
+        reason: 'worktree limpio, propio e integrado; eliminación confirmada.',
+    };
+}
+export function planReap(worktrees, options) {
+    const report = { keep: [], ask: [], remove: [] };
+    for (const facts of worktrees) {
+        const plan = decideWorktree(facts, options);
+        report[plan.decision === 'keep' ? 'keep' : plan.decision === 'ask' ? 'ask' : 'remove'].push(plan);
+    }
+    return report;
+}

package/dist/manifest/build.d.ts

@@ -0,0 +1 @@
+export { buildInventory, checkInventory, inventoryPath, serializeInventory, writeInventory, } from './manifest.js';

package/dist/manifest/build.js

@@ -0,0 +1 @@
+export { buildInventory, checkInventory, inventoryPath, serializeInventory, writeInventory, } from './manifest.js';

package/dist/manifest/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};