hammoc 1.5.0 → 1.7.0

package/packages/server/dist/services/harnessBundleService.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Story 30.5 (Task A): Harness Export/Import bundle service — server-side
+ * single source of truth that backs the 4 REST endpoints
+ * (`/api/harness/bundle/export`, `.../import/preview`, `.../import/apply`,
+ * `.../plugin-deps`).
+ *
+ * Two public methods:
+ *   - `export({ projectSlug, includes, secretsPolicy, acknowledgedSecretInclusion? })`
+ *     produces a single `{ zipBuffer, manifest, filename }` triple. The ZIP
+ *     contains `manifest.json` at the root plus the 5 R/W domain artefacts +
+ *     CLAUDE.md + BMad core-config (when opted in). Each text payload is
+ *     filtered through the chosen secrets policy via the helpers absorbed from
+ *     Task 2 (`applyPolicyToValue` / `applyPolicyToText`). For the
+ *     `included-explicit` policy the filename is force-suffixed with
+ *     `-WITH-SECRETS` and the caller must supply
+ *     `acknowledgedSecretInclusion: true` or the call throws AC2.d-2.
+ *
+ *   - `import({ projectSlug, zipBuffer, dryRun, itemActions? })` parses the ZIP,
+ *     runs Zod validation of `manifest.json`, computes a per-item preview
+ *     (`new`/`overwrite`/`same`/`conflict`) by comparing each bundle item to
+ *     the current project state, and — when `dryRun === false` — applies the
+ *     selected `itemActions` inside a single in-memory transaction. Pre-state
+ *     snapshots are captured up-front so a mid-flight failure can be reversed
+ *     in reverse order (AC1 + A.3 rollback semantics).
+ *
+ * Single sources of truth this service depends on (no duplicate logic here):
+ *   - `secretHeuristic.ts`  (Story 30.1)  → pattern detection
+ *   - `applySecretsPolicy.ts` (Task 2)    → 3-policy payload rewriting
+ *   - `secretPlaceholderNamer.ts` (Task 2) → ENV-ref naming for placeholder mode
+ *   - `harnessBundleSchema.ts` (Task 4)   → Zod validation of manifest.json
+ *   - `assertSafeBundlePath.ts` (Task A.5) → ZIP-slip guard for every entry
+ *
+ * The bundle service intentionally does file I/O via raw `fs` (with a
+ * `fileWatcherService.noteLocalWrite` call after each write) rather than
+ * routing through the per-domain services. Reasons:
+ *   1. The per-domain services have card-shaped (un-grouped) input/output —
+ *      a bundle round-trip needs file-shaped I/O.
+ *   2. The per-domain services contain Story-30.1 share-scope guards that
+ *      block plaintext secrets on shared paths; the bundle import path lets
+ *      `included-explicit` bundles land plaintext into the project (that is
+ *      the entire point of the policy) so going through the share-scope
+ *      guard would be wrong.
+ *   3. The `pendingLocalWrites` echo-suppression window is wired directly on
+ *      `fileWatcherService` so calling `noteLocalWrite` is sufficient — see
+ *      `harnessService.write` which does the same pair (`fs.writeFile` +
+ *      `noteLocalWrite`) under the hood.
+ */
+import { type BundleManifest, type BundlePluginRef, type BundleSection, type ImportApplySummary, type ImportCompatibility, type ImportCompatibilityDetail, type ImportItemAction, type ImportPreview, type SecretsPolicy } from '@hammoc/shared';
+export interface ExportInput {
+    projectSlug: string;
+    includes: BundleSection[];
+    secretsPolicy: SecretsPolicy;
+    /** Required + must equal `true` when `secretsPolicy === 'included-explicit'`. */
+    acknowledgedSecretInclusion?: boolean;
+}
+export interface ExportOutput {
+    zipBuffer: Buffer;
+    manifest: BundleManifest;
+    /** Final filename (with `-WITH-SECRETS` enforced when applicable). */
+    filename: string;
+    secretsRemovedCount: number;
+    secretsReplacedCount: number;
+    hadPlaintextSecrets: boolean;
+}
+export interface ImportInput {
+    projectSlug: string;
+    zipBuffer: Buffer;
+    /** When true, no R/W happens — only the preview is returned. */
+    dryRun: boolean;
+    /** Maps `"<domain>:<identity>"` → chosen action. Ignored when `dryRun`. */
+    itemActions?: Record<string, ImportItemAction>;
+}
+export interface ImportResult {
+    manifest: BundleManifest;
+    preview: ImportPreview;
+    compatibility: ImportCompatibility;
+    compatibilityDetail?: ImportCompatibilityDetail;
+    appliedSummary?: ImportApplySummary;
+}
+/**
+ * Cached entry inside the in-memory `bundleTokenStore`. Lookup is by token —
+ * the preview request stashes the parsed ZIP + manifest, the apply call
+ * resolves the token and consumes the entry exactly once.
+ */
+interface BundleTokenEntry {
+    projectSlug: string;
+    zipBuffer: Buffer;
+    manifest: BundleManifest;
+    insertedAt: number;
+}
+declare class HarnessBundleService {
+    /**
+     * Token → bundle map. Preview stashes the ZIP keyed by a UUID; apply
+     * resolves the token to retrieve the same buffer the user previewed. Stale
+     * entries past the TTL are GC'd lazily on every preview/apply call.
+     */
+    private readonly bundleTokens;
+    export(input: ExportInput): Promise<ExportOutput>;
+    private collectClaudeMd;
+    private collectSkills;
+    private collectCommands;
+    private collectAgents;
+    private collectHooks;
+    private collectMcp;
+    private collectBmad;
+    /**
+     * Active plugin dependencies — read `installed_plugins.json` + `enabledPlugins`
+     * and emit only the entries currently enabled.
+     */
+    collectPluginDependencies(projectSlug: string): Promise<BundlePluginRef[]>;
+    /**
+     * Resolve a single path's share-scope verdict for manifest bookkeeping.
+     * Best-effort — if the share-scope service throws (project not found, etc.)
+     * we fall back to `'shared'` since we know the file already exists inside
+     * the project tree.
+     */
+    private resolveShareScope;
+    import(input: ImportInput): Promise<ImportResult>;
+    private computePreview;
+    /**
+     * Compare one bundle item to its destination on disk and produce the
+     * preview row. Status semantics: `new` → no file at target, `same` → bytes
+     * match exactly, `overwrite` → file exists with different content,
+     * `conflict` → a directory sits where a file would land (or vice versa).
+     */
+    private statusForItem;
+    private hookStatus;
+    /** Resolve where one bundle item should be written on the target project. */
+    private targetPathFor;
+    private computeMissingPlugins;
+    private applyImport;
+    /**
+     * Stash a parsed bundle + its source ZIP behind a one-time token. The token
+     * is what the apply call must echo. Tokens are GC'd lazily once they pass
+     * the TTL — a 30-minute window mirrors the export dialog session length.
+     */
+    storeBundle(projectSlug: string, zipBuffer: Buffer, manifest: BundleManifest): string;
+    consumeBundle(token: string): BundleTokenEntry | null;
+    releaseBundle(token: string): void;
+    private gcTokenStore;
+}
+export declare const harnessBundleService: HarnessBundleService;
+export { HarnessBundleService };
+export { UnsafeBundlePathError } from '../utils/assertSafeBundlePath.js';
+//# sourceMappingURL=harnessBundleService.d.ts.map

package/packages/server/dist/services/harnessBundleService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"harnessBundleService.d.ts","sourceRoot":"","sources":["../../src/services/harnessBundleService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAOH,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,aAAa,EAGlB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,gBAAgB,EAGrB,KAAK,aAAa,EAElB,KAAK,aAAa,EACnB,MAAM,gBAAgB,CAAC;AAuMxB,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,aAAa,EAAE,aAAa,CAAC;IAC7B,iFAAiF;IACjF,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,cAAc,CAAC;IACzB,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;IACjB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,MAAM,EAAE,OAAO,CAAC;IAChB,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,cAAc,CAAC;IACzB,OAAO,EAAE,aAAa,CAAC;IACvB,aAAa,EAAE,mBAAmB,CAAC;IACnC,mBAAmB,CAAC,EAAE,yBAAyB,CAAC;IAChD,cAAc,CAAC,EAAE,kBAAkB,CAAC;CACrC;AAED;;;;GAIG;AACH,UAAU,gBAAgB;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,cAAc,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,cAAM,oBAAoB;IACxB;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAuC;IAI9D,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;YA+FzC,eAAe;YAgCf,aAAa;YAuFb,eAAe;YAiDf,aAAa;YAqDb,YAAY;YAoEZ,UAAU;YAgDV,WAAW;IAmCzB;;;OAGG;IACG,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAqBhF;;;;;OAKG;YACW,iBAAiB;IAoBzB,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;YAyFzC,cAAc;IA6C5B;;;;;OAKG;YACW,aAAa;YAkDb,UAAU;IAoCxB,6EAA6E;IAC7E,OAAO,CAAC,aAAa;YA0BP,qBAAqB;YAuBrB,WAAW;IA8UzB;;;;OAIG;IACH,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,GAAG,MAAM;IAYrF,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI;IAOrD,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIlC,OAAO,CAAC,YAAY;CAQrB;AAsDD,eAAO,MAAM,oBAAoB,sBAA6B,CAAC;AAC/D,OAAO,EAAE,oBAAoB,EAAE,CAAC;AAGhC,OAAO,EAAE,qBAAqB,EAAE,MAAM,kCAAkC,CAAC"}