hadara 0.1.0-rc.0

package/dist/schemas/smoke-evidence-summary.schema.json

@@ -0,0 +1,88 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "hadara.smokeEvidenceSummary.v1",
+    "x-hadara-schema-id": "hadara.smokeEvidenceSummary.v1",
+    "title": "HADARA Smoke Evidence Summary",
+    "type": "object",
+    "additionalProperties": true,
+    "required": [
+        "schemaVersion",
+        "time",
+        "taskId",
+        "category",
+        "sourceReport",
+        "execution",
+        "steps",
+        "privacy",
+        "issues",
+        "rawLogsIncluded",
+        "privatePathsIncluded",
+        "rawPackageContentsIncluded"
+    ],
+    "properties": {
+        "schemaVersion": { "const": "hadara.smokeEvidenceSummary.v1" },
+        "time": { "type": "string", "minLength": 1 },
+        "taskId": { "type": "string", "pattern": "^T-[0-9]{4}$" },
+        "category": { "type": "string", "enum": ["package-smoke", "clean-checkout-smoke"] },
+        "sourceReport": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["schemaVersion", "command", "mode", "ok"],
+            "properties": {
+                "schemaVersion": { "type": "string", "minLength": 1 },
+                "command": { "type": "string", "minLength": 1 },
+                "mode": { "type": "string", "minLength": 1 },
+                "ok": { "type": "boolean" }
+            }
+        },
+        "execution": { "type": "object", "additionalProperties": true },
+        "steps": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/step" }
+        },
+        "privacy": {
+            "type": "object",
+            "additionalProperties": true,
+            "properties": {
+                "rawLogsIncluded": { "const": false },
+                "rawPackageContentsIncluded": { "const": false },
+                "privatePathsIncluded": { "const": false },
+                "environmentSecretsIncluded": { "const": false },
+                "privateStorePathsIncluded": { "const": false }
+            }
+        },
+        "issues": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/issue" }
+        },
+        "rawLogsIncluded": { "const": false },
+        "privatePathsIncluded": { "const": false },
+        "rawPackageContentsIncluded": { "const": false }
+    },
+    "$defs": {
+        "step": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["id", "label", "status", "summary"],
+            "properties": {
+                "id": { "type": "string", "minLength": 1 },
+                "label": { "type": "string", "minLength": 1 },
+                "status": { "type": "string", "enum": ["planned", "passed", "failed", "skipped"] },
+                "exitCode": { "type": ["integer", "null"] },
+                "elapsedMs": { "type": "integer" },
+                "summary": { "type": "string", "minLength": 1 }
+            }
+        },
+        "issue": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["severity", "code", "message"],
+            "properties": {
+                "severity": { "type": "string", "enum": ["warning", "error"] },
+                "code": { "type": "string", "minLength": 1 },
+                "message": { "type": "string", "minLength": 1 },
+                "stepId": { "type": "string", "minLength": 1 }
+            }
+        }
+    }
+}

package/dist/schemas/tools-list.schema.json

@@ -0,0 +1,78 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "hadara.tools.list.v1",
+    "x-hadara-schema-id": "hadara.tools.list.v1",
+    "title": "HADARA Tools List Report",
+    "type": "object",
+    "additionalProperties": true,
+    "required": ["schemaVersion", "command", "ok", "surfaces", "disabled", "issues"],
+    "properties": {
+        "schemaVersion": { "const": "hadara.tools.list.v1" },
+        "command": { "const": "tools.list" },
+        "ok": { "const": true },
+        "surfaces": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["cli", "mcp"],
+            "properties": {
+                "cli": {
+                    "type": "array",
+                    "items": { "$ref": "#/$defs/surface" }
+                },
+                "mcp": {
+                    "type": "array",
+                    "items": { "$ref": "#/$defs/surface" }
+                }
+            }
+        },
+        "disabled": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/disabledSurface" }
+        },
+        "issues": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/issue" }
+        }
+    },
+    "$defs": {
+        "surface": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["name", "category", "stable", "readOnly", "enabledByDefault", "availability", "risk"],
+            "properties": {
+                "name": { "type": "string", "minLength": 1 },
+                "category": { "type": "string", "enum": ["read", "write", "execute", "provider", "release"] },
+                "stable": { "type": "boolean" },
+                "readOnly": { "type": "boolean" },
+                "enabledByDefault": { "type": "boolean" },
+                "availability": { "type": "string", "enum": ["default", "opt-in", "disabled", "deferred"] },
+                "risk": { "type": "string", "enum": ["low", "medium", "high"] },
+                "requiresApproval": { "type": "boolean" },
+                "schemaVersion": { "type": "string", "minLength": 1 },
+                "notes": { "type": "string", "minLength": 1 }
+            }
+        },
+        "disabledSurface": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["name", "category", "availability", "risk", "reason"],
+            "properties": {
+                "name": { "type": "string", "minLength": 1 },
+                "category": { "type": "string", "enum": ["read", "write", "execute", "provider", "release"] },
+                "availability": { "type": "string", "enum": ["disabled", "deferred"] },
+                "risk": { "type": "string", "enum": ["low", "medium", "high"] },
+                "reason": { "type": "string", "minLength": 1 }
+            }
+        },
+        "issue": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["severity", "code", "message"],
+            "properties": {
+                "severity": { "type": "string", "enum": ["warning", "error"] },
+                "code": { "type": "string", "minLength": 1 },
+                "message": { "type": "string", "minLength": 1 }
+            }
+        }
+    }
+}

package/dist/schemas/write-preflight.schema.json

@@ -0,0 +1,47 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "hadara.write.preflight.v1",
+    "x-hadara-schema-id": "hadara.write.preflight.v1",
+    "title": "HADARA CLI Write Preflight Report",
+    "type": "object",
+    "additionalProperties": true,
+    "required": ["schemaVersion", "ok", "command", "risk", "requiresApproval", "workspaceBoundary", "writes", "issues"],
+    "properties": {
+        "schemaVersion": { "const": "hadara.write.preflight.v1" },
+        "ok": { "type": "boolean" },
+        "command": {
+            "type": "string",
+            "enum": [
+                "task.create",
+                "evidence.collect",
+                "handoff.update",
+                "run-state.start",
+                "run-state.update",
+                "run-state.complete",
+                "debt.add",
+                "debt.update",
+                "unknown"
+            ]
+        },
+        "risk": { "type": "string", "enum": ["low", "medium", "high"] },
+        "requiresApproval": { "type": "boolean" },
+        "workspaceBoundary": { "type": "string", "enum": ["project", "project+private-portable"] },
+        "writes": {
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 }
+        },
+        "issues": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "additionalProperties": true,
+                "required": ["severity", "code", "message"],
+                "properties": {
+                    "severity": { "type": "string", "enum": ["warning", "error"] },
+                    "code": { "type": "string", "minLength": 1 },
+                    "message": { "type": "string", "minLength": 1 }
+                }
+            }
+        }
+    }
+}

package/dist/services/active-run-state.js

@@ -0,0 +1,215 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.activeRunManifestPath = activeRunManifestPath;
+exports.activeRunManifestPortablePath = activeRunManifestPortablePath;
+exports.createActiveRunManifest = createActiveRunManifest;
+exports.writeActiveRunManifest = writeActiveRunManifest;
+exports.readActiveRunManifest = readActiveRunManifest;
+exports.createActiveRunProjection = createActiveRunProjection;
+exports.safeCreateActiveRunProjection = safeCreateActiveRunProjection;
+exports.createActiveRunResumeReport = createActiveRunResumeReport;
+exports.assertActiveRunProjectionSchema = assertActiveRunProjectionSchema;
+exports.assertActiveRunResumeSchema = assertActiveRunResumeSchema;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const fs_1 = require("../core/fs");
+const schema_1 = require("../core/schema");
+const task_capsule_1 = require("../task/task-capsule");
+const project_read_model_1 = require("./project-read-model");
+class ActiveRunManifestReadError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ActiveRunManifestReadError';
+    }
+}
+function activeRunManifestPath(projectRoot) {
+    return node_path_1.default.join(projectRoot, '.hadara', 'local', 'state', 'active-run.json');
+}
+function activeRunManifestPortablePath() {
+    return '.hadara/local/state/active-run.json';
+}
+function createActiveRunManifest(projectRoot, input) {
+    const task = (0, task_capsule_1.listTaskCapsules)(projectRoot).find((item) => item.id === input.taskId);
+    return {
+        schemaVersion: 'hadara.active_run.v1',
+        runId: input.runId,
+        taskId: input.taskId,
+        capsule: task ? toPortablePath(node_path_1.default.relative(projectRoot, task.dir)) : '',
+        status: input.status ?? 'active',
+        startedAt: input.startedAt,
+        updatedAt: input.updatedAt ?? input.startedAt,
+        summary: input.summary
+    };
+}
+function writeActiveRunManifest(projectRoot, manifest) {
+    const filePath = activeRunManifestPath(projectRoot);
+    (0, fs_1.ensureDir)(node_path_1.default.dirname(filePath));
+    node_fs_1.default.writeFileSync(filePath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+}
+function readActiveRunManifest(projectRoot) {
+    const filePath = activeRunManifestPath(projectRoot);
+    if (!node_fs_1.default.existsSync(filePath))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(node_fs_1.default.readFileSync(filePath, 'utf8'));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new ActiveRunManifestReadError(message);
+    }
+    if (!isActiveRunManifest(parsed)) {
+        throw new ActiveRunManifestReadError(`${activeRunManifestPortablePath()} is not a valid active run manifest.`);
+    }
+    return parsed;
+}
+function createActiveRunProjection(projectRoot) {
+    const activeRun = readActiveRunManifest(projectRoot);
+    const issues = [];
+    const task = activeRun ? (0, task_capsule_1.listTaskCapsules)(projectRoot).find((item) => item.id === activeRun.taskId) : undefined;
+    const canonicalCapsule = task ? toPortablePath(node_path_1.default.relative(projectRoot, task.dir)) : null;
+    const staleReason = activeRun ? findStaleHandoffReason(projectRoot, activeRun) : null;
+    const taskMissing = activeRun ? !task : false;
+    const capsuleMismatch = activeRun && canonicalCapsule !== null && activeRun.capsule !== canonicalCapsule;
+    if (staleReason) {
+        issues.push({
+            severity: 'warning',
+            code: 'ACTIVE_RUN_HANDOFF_STALE',
+            message: staleReason
+        });
+    }
+    if (activeRun && taskMissing) {
+        issues.push({
+            severity: 'warning',
+            code: 'ACTIVE_RUN_TASK_NOT_FOUND',
+            message: `Active run ${activeRun.taskId} has no matching Task Capsule.`
+        });
+    }
+    if (activeRun && capsuleMismatch) {
+        issues.push({
+            severity: 'warning',
+            code: 'ACTIVE_RUN_CAPSULE_MISMATCH',
+            message: `Active run ${activeRun.taskId} points to ${activeRun.capsule || '(empty capsule)'}, but the canonical Task Capsule path is ${canonicalCapsule}.`
+        });
+    }
+    const resumeCapsule = canonicalCapsule ?? activeRun?.capsule ?? '';
+    const report = {
+        schemaVersion: 'hadara.active_run.projection.v1',
+        command: 'active-run.projection',
+        ok: true,
+        path: activeRunManifestPortablePath(),
+        activeRun,
+        handoff: {
+            fresh: staleReason === null,
+            staleReason
+        },
+        resume: activeRun
+            ? {
+                taskId: activeRun.taskId,
+                capsule: resumeCapsule,
+                nextAction: taskMissing
+                    ? `Resolve missing Task Capsule for ${activeRun.taskId} before resuming.`
+                    : `Resume ${activeRun.taskId} from ${resumeCapsule || activeRunManifestPortablePath()}.`
+            }
+            : null,
+        issues
+    };
+    assertActiveRunProjectionSchema(report);
+    return report;
+}
+function safeCreateActiveRunProjection(projectRoot) {
+    try {
+        return createActiveRunProjection(projectRoot);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const code = error instanceof ActiveRunManifestReadError ? 'ACTIVE_RUN_MANIFEST_INVALID' : 'ACTIVE_RUN_REPORT_SCHEMA_INVALID';
+        const staleReason = error instanceof ActiveRunManifestReadError
+            ? `${activeRunManifestPortablePath()} could not be read.`
+            : `${activeRunManifestPortablePath()} produced an invalid active-run report.`;
+        const report = {
+            schemaVersion: 'hadara.active_run.projection.v1',
+            command: 'active-run.projection',
+            ok: true,
+            path: activeRunManifestPortablePath(),
+            activeRun: null,
+            handoff: {
+                fresh: false,
+                staleReason
+            },
+            resume: null,
+            issues: [
+                {
+                    severity: 'warning',
+                    code,
+                    message
+                }
+            ]
+        };
+        assertActiveRunProjectionSchema(report);
+        return report;
+    }
+}
+function createActiveRunResumeReport(projectRoot) {
+    const projection = safeCreateActiveRunProjection(projectRoot);
+    const activeRun = projection.activeRun;
+    const taskId = activeRun?.taskId ?? null;
+    const capsule = projection.resume?.capsule || activeRun?.capsule || (taskId ? `tasks/${taskId}` : null);
+    const report = {
+        schemaVersion: 'hadara.active_run.resume.v1',
+        command: 'active-run.resume',
+        ok: true,
+        activeRun,
+        resumePrompt: {
+            summary: activeRun ? `Continue ${activeRun.taskId}: ${activeRun.summary}` : 'No active run is currently recorded.',
+            mustRead: activeRun
+                ? ['docs/AGENT_HANDOFF.md', `${capsule}/TASK.md`, `${capsule}/HANDOFF.md`]
+                : ['docs/AGENT_HANDOFF.md', 'docs/TASK_BOARD.md'],
+            nextActions: activeRun
+                ? [projection.resume?.nextAction ?? `Resume ${activeRun.taskId}.`, 'Run required validation before marking the task Done.']
+                : ['Pick or create one Task Capsule before implementation.', 'Follow docs/AGENT_HANDOFF.md for the next recommended step.'],
+            constraints: [
+                'Do not assume multi-agent queues.',
+                'Do not use MCP write tools for active-run mutation.',
+                'Attach evidence before marking work Done.'
+            ]
+        },
+        issues: projection.issues
+    };
+    assertActiveRunResumeSchema(report);
+    return report;
+}
+function assertActiveRunProjectionSchema(report) {
+    (0, schema_1.assertSchema)('hadara.active_run.projection.v1', report);
+}
+function assertActiveRunResumeSchema(report) {
+    (0, schema_1.assertSchema)('hadara.active_run.resume.v1', report);
+}
+function findStaleHandoffReason(projectRoot, activeRun) {
+    const sources = (0, project_read_model_1.readProjectSources)(projectRoot);
+    if (!sources.handoff.exists)
+        return `Active run ${activeRun.taskId} exists, but docs/AGENT_HANDOFF.md is missing.`;
+    if (!sources.handoff.content.includes(activeRun.taskId)) {
+        return `Active run ${activeRun.taskId} is not mentioned in docs/AGENT_HANDOFF.md.`;
+    }
+    return null;
+}
+function isActiveRunManifest(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const candidate = value;
+    return (candidate.schemaVersion === 'hadara.active_run.v1' &&
+        typeof candidate.runId === 'string' &&
+        typeof candidate.taskId === 'string' &&
+        typeof candidate.capsule === 'string' &&
+        (candidate.status === 'active' || candidate.status === 'paused') &&
+        typeof candidate.startedAt === 'string' &&
+        typeof candidate.updatedAt === 'string' &&
+        typeof candidate.summary === 'string');
+}
+function toPortablePath(value) {
+    return value.split(node_path_1.default.sep).join('/');
+}