@paths.design/caws-cli 11.1.7 → 11.1.8

package/dist/store/specs-writer.d.ts

@@ -1,4 +1,5 @@
 import { type EventBody, type Result, type Spec, type Diagnostic } from '@paths.design/caws-kernel';
+import { type AutoCommitOutcome } from './git-autocommit';
 export interface CreateSpecInput {
     readonly id: string;
     readonly title: string;
@@ -20,42 +21,168 @@ export interface CloseSpecInput {
     readonly now?: () => Date;
     readonly actor: EventBody['actor'];
 }
+export interface ActivateSpecInput {
+    readonly id: string;
+    readonly now?: () => Date;
+    readonly actor: EventBody['actor'];
+}
 export interface ArchiveSpecInput {
     readonly id: string;
     readonly reason?: string;
     readonly now?: () => Date;
     readonly actor: EventBody['actor'];
 }
+export interface RetireDraftSpecInput {
+    readonly id: string;
+    readonly reason?: string;
+    readonly now?: () => Date;
+    readonly actor: EventBody['actor'];
+}
 export type SpecWriterOutcome = {
     readonly kind: 'success';
     readonly id: string;
     readonly path: string;
+    /**
+     * Audit-commit outcome for the spec yaml write
+     * (CAWS-SPECS-WRITER-AUTOCOMMIT-001). Always present on success.
+     * Callers that want the sha can read `data.audit_commit.sha` when
+     * `data.audit_commit.kind === 'committed'`. Refused or skipped
+     * outcomes are non-fatal: the writer's transaction still
+     * succeeded; only the audit-trail commit was deferred.
+     */
+    readonly data?: {
+        readonly audit_commit: AutoCommitOutcome;
+    };
 } | {
     readonly kind: 'partial_failure_recovered';
     readonly cause: readonly Diagnostic[];
 };
 export declare function createSpec(cawsDir: string, input: CreateSpecInput): Result<SpecWriterOutcome>;
+export declare function activateSpec(cawsDir: string, input: ActivateSpecInput): Result<SpecWriterOutcome>;
 export declare function closeSpec(cawsDir: string, input: CloseSpecInput): Result<SpecWriterOutcome>;
 export declare function archiveSpec(cawsDir: string, input: ArchiveSpecInput): Result<SpecWriterOutcome>;
+export declare function retireDraftSpec(cawsDir: string, input: RetireDraftSpecInput): Result<SpecWriterOutcome>;
 export interface SpecsListEntry {
     readonly id: string;
     readonly title: string;
     readonly lifecycle_state: string;
     readonly path: string;
 }
+/**
+ * CAWS-ARCHIVE-AS-TOMBSTONE-001: archived entries do NOT have an
+ * on-disk path post-tombstone. They are reconstructed from the event
+ * log's spec_archived events. `blob_sha` is the recovery target;
+ * `path` carries the from_path (where the spec was BEFORE archiving)
+ * for human-readable identification.
+ */
+export interface ArchivedSpecsListEntry {
+    readonly id: string;
+    /**
+     * Pre-archive from_path. For new-shape events, taken verbatim from
+     * the event's from_path. For legacy events, the same field
+     * (legacy events also carry from_path).
+     */
+    readonly path: string;
+    readonly archived_at: string;
+    /**
+     * Blob sha of the spec body at archive time. `null` for legacy
+     * events (pre-tombstone shape with no blob_sha); recovery in that
+     * case uses git log --follow fallback.
+     */
+    readonly blob_sha: string | null;
+}
 export interface SpecsListResult {
     readonly active: readonly SpecsListEntry[];
-    readonly archived: readonly SpecsListEntry[];
+    readonly archived: readonly ArchivedSpecsListEntry[];
 }
-/** List specs by lifecycle state, optionally including archived ones. */
+/**
+ * List specs by lifecycle state, optionally including archived ones.
+ *
+ * CAWS-ARCHIVE-AS-TOMBSTONE-001: the `--include-archived` path now
+ * reads from `.caws/events.jsonl` (most recent spec_archived event
+ * per spec_id), NOT from `.caws/specs/.archive/`. Post-tombstone the
+ * .archive/ directory is not populated; reading it would either
+ * surface nothing (steady state) or surface legacy bodies the
+ * doctor warning already flags for migration.
+ *
+ * Includes legacy events (with only from_path + to_path, no
+ * blob_sha) → blob_sha is reported as null; recover falls back to
+ * git log --follow.
+ *
+ * Latest-write-wins per spec_id: if a spec was archived, recovered,
+ * recreated, and re-archived, only the most recent spec_archived
+ * event surfaces.
+ */
 export declare function listSpecs(cawsDir: string, options?: {
     readonly includeArchived?: boolean;
 }): Result<SpecsListResult>;
-/** Find a spec by id under active or archive locations. */
+/**
+ * Find a spec by id in the ACTIVE location only
+ * (.caws/specs/<id>.yaml). CAWS-ARCHIVE-AS-TOMBSTONE-001 invariant:
+ * `caws specs show` defaults to active specs only. Archived specs
+ * require explicit opt-in via `--archived` (which routes through
+ * `recoverArchivedSpec` below).
+ *
+ * Pre-tombstone: showSpec searched both active AND .caws/specs/.archive/
+ * transparently. That transparent fallback was a context-rot vector
+ * (agents grep'd and cited stale specs as authority); it is removed
+ * by design.
+ */
 export declare function showSpec(cawsDir: string, id: string): Result<{
     readonly spec: Spec;
     readonly path: string;
     readonly source: string;
 }>;
+/**
+ * Recover an archived spec's body from git history.
+ *
+ * Resolution order:
+ *   1. New-shape event with blob_sha → `git show <blob_sha>`.
+ *   2. Legacy event with to_path only → `git log --all --follow --
+ *      <from_path>` to find a containing commit, then
+ *      `git show <commit>:<from_path>`. If zero commits, Err.
+ *
+ * NEVER mutates .caws/specs/. Returns the raw yaml bytes.
+ */
+export declare function recoverArchivedSpec(cawsDir: string, id: string): Result<{
+    readonly source: string;
+    readonly blob_sha: string | null;
+    readonly from_path: string;
+}>;
+export type PruneArchivePlan = {
+    readonly id: string;
+    readonly fromPath: string;
+    readonly fromRel: string;
+    readonly status: 'recoverable';
+    readonly blob_sha: string;
+    readonly commit_sha: string;
+} | {
+    readonly id: string;
+    readonly fromPath: string;
+    readonly fromRel: string;
+    readonly status: 'unrecoverable';
+    readonly reason: string;
+};
+export interface PruneArchiveResult {
+    readonly plans: ReadonlyArray<PruneArchivePlan>;
+    readonly applied: boolean;
+    readonly events_appended: number;
+}
+export interface PruneArchiveInput {
+    readonly apply?: boolean;
+    readonly actor: EventBody['actor'];
+    readonly now?: () => Date;
+}
+/**
+ * Scan .caws/specs/.archive/ for legacy bodies. Returns per-id status
+ * (dry-run) or executes the migration (--apply).
+ *
+ * Recoverability check: `git log --all --follow -- <fromPath>`. If
+ * any commit contains the file, the body is recoverable from git
+ * history; we extract the blob_sha + most-recent containing commit
+ * and that becomes the recovery target. If zero commits, the body
+ * is local-only and gets quarantined.
+ */
+export declare function pruneArchive(cawsDir: string, input: PruneArchiveInput): Result<PruneArchiveResult>;
 export type { EventBody };
 //# sourceMappingURL=specs-writer.d.ts.map

package/dist/store/specs-writer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"specs-writer.d.ts","sourceRoot":"","sources":["../../src/store/specs-writer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"specs-writer.d.ts","sourceRoot":"","sources":["../../src/store/specs-writer.ts"],"names":[],"mappings":"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"}