@chinhae/atw-cli 0.1.0

package/dist/types/migration.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Migration types for ATW update command
+ *
+ * These types support intelligent migration during updates,
+ * handling file renames, deletions, and user modification detection.
+ */
+/**
+ * A single migration action (rename, rename-dir, or delete)
+ */
+export interface MigrationItem {
+    /** Type of migration action */
+    type: "rename" | "rename-dir" | "delete" | "safe-file-delete";
+    /** Source path (relative to project root) */
+    from: string;
+    /** Target path for renames (relative to project root) */
+    to?: string;
+    /** Human-readable description of WHAT this migration does */
+    description?: string;
+    /**
+     * Optional context shown in the "confirm" prompt explaining WHY the user is
+     * being asked about this specific file. Use this for version-specific nuance
+     * (e.g. a known hash-tracking gap from a prior CLI version) that would
+     * otherwise have to be hardcoded in update.ts. Keep it short (1-2 sentences).
+     */
+    reason?: string;
+    /** Known template hashes for safe-file-delete (only delete if content matches) */
+    allowed_hashes?: string[];
+}
+/**
+ * A new top-level config.yaml section introduced by this release.
+ *
+ * Used by `atw update` to append the section to existing user config files
+ * that pre-date the release, without overwriting their other customizations.
+ * Append is gated on `sentinel`: if the user file already contains the sentinel
+ * substring (live or commented), the section is treated as already present.
+ */
+export interface ConfigSectionAdded {
+    /** Target file relative to project root (e.g. `.atw/config.yaml`). */
+    file: string;
+    /**
+     * Substring whose presence in the user file means this section already
+     * exists. Pick something stable (e.g. the new top-level YAML key like
+     * `codex:`).
+     */
+    sentinel: string;
+    /**
+     * The section heading text that appears on the `# <heading>` line inside the
+     * `#---` separator block in the bundled template. The extractor takes lines
+     * from that separator block until the next `#---` separator (or EOF).
+     */
+    sectionHeading: string;
+}
+/**
+ * Migration manifest for a specific version
+ */
+export interface MigrationManifest {
+    /** Target version this migration upgrades to */
+    version: string;
+    /** Human-readable description of changes in this version */
+    description?: string;
+    /** List of migration actions */
+    migrations: MigrationItem[];
+    /** Detailed changelog for display to users */
+    changelog?: string;
+    /** Whether this version contains breaking changes */
+    breaking?: boolean;
+    /** Whether users should run --migrate (recommended for breaking changes) */
+    recommendMigrate?: boolean;
+    /** Detailed migration guide for AI-assisted fixes (markdown format) */
+    migrationGuide?: string;
+    /** Instructions for AI assistants on how to help with migration */
+    aiInstructions?: string;
+    /**
+     * New top-level config.yaml sections introduced by this release. Applied
+     * additively to existing user files via sentinel-gated append, keeping their
+     * customizations intact while still surfacing newly-introduced knobs.
+     */
+    configSectionsAdded?: ConfigSectionAdded[];
+}
+/**
+ * Classification of how a migration should be handled
+ */
+export type MigrationClassification = "auto" | "confirm" | "conflict" | "skip";
+/**
+ * Classified migration item with its determined action
+ */
+export interface ClassifiedMigrationItem extends MigrationItem {
+    classification: MigrationClassification;
+}
+/**
+ * Result of classifying all migrations
+ */
+export interface ClassifiedMigrations {
+    /** Unmodified files - safe to auto-migrate */
+    auto: MigrationItem[];
+    /** User-modified files - need confirmation */
+    confirm: MigrationItem[];
+    /** Conflict - both old and new exist */
+    conflict: MigrationItem[];
+    /** Skip - old file doesn't exist */
+    skip: MigrationItem[];
+}
+/**
+ * Result of executing migrations
+ */
+export interface MigrationResult {
+    /** Number of files renamed */
+    renamed: number;
+    /** Number of files deleted */
+    deleted: number;
+    /** Number of files skipped (user choice or no action needed) */
+    skipped: number;
+    /** Number of conflicts encountered */
+    conflicts: number;
+}
+/**
+ * User action choice for migration confirmation
+ */
+export type MigrationAction = "rename" | "backup-rename" | "skip" | "view-diff";
+/**
+ * Template hashes storage structure
+ * Maps relative file paths to their SHA256 hashes
+ */
+export type TemplateHashes = Record<string, string>;
+//# sourceMappingURL=migration.d.ts.map

package/dist/types/migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration.d.ts","sourceRoot":"","sources":["../../src/types/migration.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,+BAA+B;IAC/B,IAAI,EAAE,QAAQ,GAAG,YAAY,GAAG,QAAQ,GAAG,kBAAkB,CAAC;IAC9D,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gCAAgC;IAChC,UAAU,EAAE,aAAa,EAAE,CAAC;IAC5B,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,uEAAuE;IACvE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mEAAmE;IACnE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,kBAAkB,EAAE,CAAC;CAC5C;AAED;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAC/B,MAAM,GACN,SAAS,GACT,UAAU,GACV,MAAM,CAAC;AAEX;;GAEG;AACH,MAAM,WAAW,uBAAwB,SAAQ,aAAa;IAC5D,cAAc,EAAE,uBAAuB,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,8CAA8C;IAC9C,IAAI,EAAE,aAAa,EAAE,CAAC;IACtB,8CAA8C;IAC9C,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,wCAAwC;IACxC,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,oCAAoC;IACpC,IAAI,EAAE,aAAa,EAAE,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GACvB,QAAQ,GACR,eAAe,GACf,MAAM,GACN,WAAW,CAAC;AAEhB;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC"}

package/dist/types/migration.js

@@ -0,0 +1,8 @@
+/**
+ * Migration types for ATW update command
+ *
+ * These types support intelligent migration during updates,
+ * handling file renames, deletions, and user modification detection.
+ */
+export {};
+//# sourceMappingURL=migration.js.map

package/dist/types/migration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration.js","sourceRoot":"","sources":["../../src/types/migration.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/utils/ablation-store.d.ts

@@ -0,0 +1,123 @@
+/**
+ * External, versioned recovery storage for reversible full ATW ablation.
+ *
+ * The store intentionally contains only manifest-owned project paths and the
+ * exact `.atw/` tree. User-authored task/spec/workspace files may contain
+ * sensitive text, so the state root is private and retained only until a
+ * verified restore. Unrelated application files and global host state are
+ * never copied.
+ */
+export declare const ABLATION_SCHEMA_VERSION = 1;
+export declare const FULL_ABLATION_CAPABILITY: "atw.full";
+export declare const ABLATION_STATE_ROOT_ENV = "ATW_ABLATION_STATE_ROOT";
+export type AblationStatus = "preparing" | "applied" | "restoring" | "conflict";
+export interface AbsentFingerprint {
+    kind: "absent";
+}
+export interface FileFingerprint {
+    kind: "file";
+    sha256: string;
+    size: number;
+    mode: number;
+}
+export interface DirectoryFingerprint {
+    kind: "directory";
+    sha256: string;
+    mode: number;
+}
+export interface SymlinkFingerprint {
+    kind: "symlink";
+    target: string;
+    mode: number;
+}
+export type PathFingerprint = AbsentFingerprint | FileFingerprint | DirectoryFingerprint | SymlinkFingerprint;
+export interface AblationEntry {
+    relativePath: string;
+    pre: PathFingerprint;
+    expectedAblated: PathFingerprint;
+    backupPath?: string;
+}
+export interface AblationStateV1 {
+    schemaVersion: 1;
+    status: AblationStatus;
+    projectRoot: string;
+    projectKey: string;
+    atwVersion: string;
+    capabilities: [typeof FULL_ABLATION_CAPABILITY];
+    createdAt: string;
+    configuredPlatforms: string[];
+    manifest: Record<string, string>;
+    entries: AblationEntry[];
+}
+export interface TransactionPaths {
+    stateRoot: string;
+    transactionDir: string;
+    stateFile: string;
+    backupDir: string;
+    lockFile: string;
+}
+export interface StagedAblationInput {
+    projectRoot: string;
+    configuredPlatforms: readonly string[];
+    manifest: Record<string, string>;
+    entries: AblationEntry[];
+}
+export interface StageAblationOptions {
+    /** The caller already holds this project's ablation-operation lock. */
+    lockHeld?: boolean;
+}
+export interface LoadedAblationTransaction {
+    paths: TransactionPaths;
+    state: AblationStateV1;
+}
+export interface RestoreAblationOptions {
+    /** Only preflight; do not transition state or restore/delete any path. */
+    dryRun?: boolean;
+    /** Delete the external transaction after verified restoration. */
+    deleteAfterRestore?: boolean;
+}
+export interface AblationConflict {
+    relativePath: string;
+    expected: PathFingerprint;
+    actual: PathFingerprint;
+}
+export declare class AblationConflictError extends Error {
+    readonly conflicts: AblationConflict[];
+    constructor(conflicts: AblationConflict[]);
+}
+/** Fingerprint one path without dereferencing a symlink leaf. */
+export declare function fingerprintPath(absPath: string): PathFingerprint;
+export declare function expectedFileFingerprint(content: string | Uint8Array, mode: number): FileFingerprint;
+export declare function fingerprintsEqual(left: PathFingerprint, right: PathFingerprint): boolean;
+export declare function canonicalProjectRoot(cwd: string): string;
+export declare function projectKey(projectRoot: string): string;
+export declare function getAblationStateRoot(): string;
+export declare function getTransactionPaths(projectRoot: string, stateRoot?: string): TransactionPaths;
+export declare function assertExternalStateRoot(projectRoot: string, stateRoot: string): void;
+/** Parse and validate an external state file. Unknown schemas fail closed. */
+export declare function parseAblationState(value: unknown): AblationStateV1;
+/**
+ * Stage and verify the complete backup, then atomically publish a `preparing`
+ * transaction before the caller mutates the project.
+ */
+export declare function stageAblationTransaction(input: StagedAblationInput, options?: StageAblationOptions): LoadedAblationTransaction;
+export declare function loadAblationTransaction(projectRoot: string, stateRoot?: string): LoadedAblationTransaction | null;
+export declare function transitionAblationState(transaction: LoadedAblationTransaction, status: AblationStatus): AblationStateV1;
+/** Serialize ablate/restore state and project mutations for one project. */
+export declare function withAblationProjectLock<T>(paths: TransactionPaths, operation: () => T): T;
+/** Preflight every affected path before restore writes anything. */
+export declare function collectRestoreConflicts(transaction: LoadedAblationTransaction): AblationConflict[];
+/** Restore exact backup bytes/link identity/modes without running preflight. */
+export declare function restoreTransactionFiles(transaction: LoadedAblationTransaction, options?: {
+    verifyExpectedState?: boolean;
+}): void;
+export declare function verifyRestoredState(transaction: LoadedAblationTransaction): void;
+export declare function verifyAblatedState(transaction: LoadedAblationTransaction): void;
+/** Conflict-safe exact restore. Any mismatch causes zero project writes. */
+export declare function restoreAblationTransaction(transaction: LoadedAblationTransaction, options?: RestoreAblationOptions): void;
+/** Roll back this process's partial ablation while holding the project lock. */
+export declare function rollbackAblationTransaction(transaction: LoadedAblationTransaction, options?: {
+    lockHeld?: boolean;
+}): void;
+export declare function deleteAblationTransaction(transaction: LoadedAblationTransaction): void;
+//# sourceMappingURL=ablation-store.d.ts.map

package/dist/utils/ablation-store.d.ts.map

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