@aperant/framework 0.6.2

package/dist/cli/install/manifest-scanner.mjs

@@ -0,0 +1,241 @@
+/**
+ * install/manifest-scanner.mjs — URL allowlist + multi-lockfile rejection (C54 R5).
+ *
+ * Runs BEFORE any install child is spawned. The scanner is a security gate
+ * that prevents `npm install` from pulling arbitrary code via a transitive
+ * `"evil": "git+ssh://hostile-host/x"` buried in a manifest or lockfile.
+ *
+ * Scope: parses manifests + lockfiles as text (we do NOT execute them) and
+ * extracts URL-like strings. Each URL is checked against the allowlist;
+ * anything outside fails the scan.
+ *
+ * Rejection categories (fatal — spawn refused, install_status = "failed"):
+ *   - Registry URLs outside the allowlist (e.g. https://internal.corp/…)
+ *   - Direct tarball URLs (https://…/archive/abc.tar.gz)
+ *   - Git+SSH deps (git+ssh://… or git@github.com:…)
+ *   - Local-path deps (file:…, link:…, path: "../…" in TOML)
+ *   - Multi-lockfile coexistence (pnpm-lock.yaml + package-lock.json, etc.)
+ *
+ * Non-rejection (allowed):
+ *   - Plain registry-resolved URLs matching the allowlist
+ *   - git+https:// deps pointing at allowlisted hosts (GitHub / GitLab /
+ *     Bitbucket) are still rejected by the git+ssh guard's stricter cousin
+ *     — see `GIT_URL_PATTERN` below; we err on the side of strict here
+ *     because transitive git deps are a common exfil vector.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Hardcoded allowlist of trusted registries. Users can override via
+ * `.aperant/config.json → task_isolation.install_registry_allowlist`.
+ *
+ * Match is hostname-based (not full URL): a URL is accepted if its
+ * hostname equals one of these entries or ends with `.<entry>` (to
+ * allow subdomain CDNs).
+ */
+export const DEFAULT_REGISTRY_ALLOWLIST = [
+    'registry.npmjs.org',
+    'registry.yarnpkg.com', // yarn's classic registry mirror
+    'pypi.org',
+    'files.pythonhosted.org',
+    'crates.io',
+    'static.crates.io',
+    'index.crates.io', // sparse index
+    'proxy.golang.org',
+    'sum.golang.org',
+    'rubygems.org',
+    'packagist.org',
+    'repo.packagist.org',
+    'repo.maven.apache.org',
+    'plugins.gradle.org',
+];
+// Known-bad prefixes that indicate hostile/unreviewable deps.
+const GIT_SSH_PATTERN = /\bgit\+ssh:\/\//i;
+const GIT_AT_PATTERN = /\bgit@([a-zA-Z0-9.-]+):/i; // git@github.com:user/repo
+const GIT_URL_PATTERN = /\bgit\+https?:\/\//i; // git+http(s)://… — still rejected (too wide)
+// Allow local-path deps that begin with `.` (relative imports in monorepos)
+// in the `workspace:*` / `link:./packages/x` form only when they resolve
+// inside the worktree. Conservative default: reject all file:/link:/path:.
+// Guard the `link:` check so it doesn't match lines that just mention the
+// word "link:" in prose / package names — require the prefix to sit at the
+// start of a value (after `"` or whitespace).
+const LOCAL_PATH_PATTERN = /["\s](file:|link:)/i;
+// TOML `path = "…"` appears both at the top of a line (classic table form)
+// and as a single-line inline-table form (`x = { path = "…" }`). Both should
+// be rejected.
+const TOML_LOCAL_PATH_PATTERN = /(^|[\s{,])path\s*=\s*["']/m;
+// Tarball URLs that are not going through a registry's "files.*" CDN.
+// Conservative: a URL ending in `.tar.gz`, `.tgz`, `.zip` that isn't under
+// an allowlisted host is rejected. (Registries like pypi serve from
+// files.pythonhosted.org; that's allowlisted.)
+const TARBALL_PATTERN = /(https?:\/\/[^\s"'<>]+\.(?:tar\.gz|tgz|zip))(?=["'\s])/gi;
+// Generic URL pattern — http(s) only (other schemes like `registry:` are
+// registry-internal and not URLs proper).
+const GENERIC_URL_PATTERN = /(https?:\/\/[^\s"'<>]+)/gi;
+/**
+ * Check whether a hostname matches the allowlist (exact or subdomain).
+ *
+ * @param {string} hostname
+ * @param {string[]} allowlist
+ * @returns {boolean}
+ */
+function isAllowlistedHost(hostname, allowlist) {
+    const host = hostname.toLowerCase();
+    for (const entry of allowlist) {
+        const e = entry.toLowerCase();
+        if (host === e)
+            return true;
+        if (host.endsWith(`.${e}`))
+            return true;
+    }
+    return false;
+}
+/**
+ * Extract URLs from a text body and classify each one. Returns a
+ * structured result the caller combines across manifests/lockfiles.
+ *
+ * @param {string} text
+ * @param {string[]} allowlist
+ * @returns {{ rejections: string[], allowed: string[] }}
+ */
+function scanText(text, allowlist) {
+    const rejections = [];
+    const allowed = [];
+    if (!text)
+        return { rejections, allowed };
+    // 1. Tarball URLs — flag before generic so we can be explicit in the reason.
+    const tarMatches = text.match(TARBALL_PATTERN) || [];
+    for (const tarUrl of tarMatches) {
+        try {
+            const u = new URL(tarUrl);
+            if (!isAllowlistedHost(u.hostname, allowlist)) {
+                rejections.push(`tarball URL outside allowlist: ${tarUrl}`);
+            }
+        }
+        catch {
+            rejections.push(`malformed tarball URL: ${tarUrl}`);
+        }
+    }
+    // 2. Generic URLs — each must resolve to an allowlisted host.
+    const genericMatches = text.match(GENERIC_URL_PATTERN) || [];
+    for (const raw of genericMatches) {
+        try {
+            const u = new URL(raw);
+            if (isAllowlistedHost(u.hostname, allowlist)) {
+                allowed.push(raw);
+            }
+            else {
+                rejections.push(`URL outside allowlist: ${raw}`);
+            }
+        }
+        catch {
+            rejections.push(`malformed URL: ${raw}`);
+        }
+    }
+    // 3. git+ssh://
+    if (GIT_SSH_PATTERN.test(text)) {
+        const m = text.match(/git\+ssh:\/\/\S+/);
+        rejections.push(`git+ssh dep rejected: ${m?.[0] ?? '(git+ssh)'}`);
+    }
+    // 4. git@host:user/repo pattern (npm/yarn shorthand)
+    const gitAt = text.match(GIT_AT_PATTERN);
+    if (gitAt) {
+        rejections.push(`git@ SSH-shorthand dep rejected: ${gitAt[0]}`);
+    }
+    // 5. git+http(s):// — also rejected (unreviewable transitive code pull)
+    if (GIT_URL_PATTERN.test(text)) {
+        const m = text.match(/git\+https?:\/\/\S+/);
+        rejections.push(`git+http(s) dep rejected: ${m?.[0] ?? '(git+https)'}`);
+    }
+    // 6. file: / link: / path: locals (JSON + TOML flavors)
+    if (LOCAL_PATH_PATTERN.test(text)) {
+        const m = text.match(/["\s](file:|link:)[^"\s]*/);
+        rejections.push(`local-path dep rejected: ${m?.[0]?.trim() ?? '(file:/link:)'}`);
+    }
+    if (TOML_LOCAL_PATH_PATTERN.test(text)) {
+        rejections.push('TOML `path = "…"` local-path dep rejected');
+    }
+    return { rejections, allowed };
+}
+/**
+ * Normalize the effective allowlist: user override wins, otherwise use the
+ * hardcoded defaults.
+ *
+ * @param {string[] | null | undefined} userAllowlist
+ * @returns {string[]}
+ */
+export function resolveAllowlist(userAllowlist) {
+    if (Array.isArray(userAllowlist) && userAllowlist.length > 0)
+        return userAllowlist;
+    return DEFAULT_REGISTRY_ALLOWLIST;
+}
+/**
+ * Scan manifests + lockfiles for every detected ecosystem.
+ *
+ * @param {string} worktreePath absolute path to the worktree dir
+ * @param {Array<{ecosystem: string, manifest: string, lockfile: string | null, multi_lockfile_paths: string[] | null}>} ecosystems
+ * @param {{ allowlist?: string[] | null }} [opts]
+ * @returns {{ ok: boolean, warnings: string[], rejections: string[], scanned_files: string[] }}
+ */
+export function scanManifests(worktreePath, ecosystems, opts = {}) {
+    const allowlist = resolveAllowlist(opts.allowlist);
+    const rejections = [];
+    const warnings = [];
+    const scannedFiles = [];
+    if (!Array.isArray(ecosystems) || ecosystems.length === 0) {
+        return { ok: true, warnings, rejections, scanned_files: scannedFiles };
+    }
+    for (const eco of ecosystems) {
+        // Multi-lockfile rejection (R2 + R5) — mtime resolution is unreliable
+        // after a git checkout.
+        if (Array.isArray(eco.multi_lockfile_paths) && eco.multi_lockfile_paths.length > 1) {
+            rejections.push(`multiple lockfiles present — delete all but one: [${eco.multi_lockfile_paths.join(', ')}]`);
+            // Don't early-return — we want to surface all rejections in one pass.
+        }
+        // Scan manifest content for hostile URLs / local-path deps.
+        if (eco.manifest) {
+            const manifestPath = join(worktreePath, eco.manifest);
+            if (existsSync(manifestPath)) {
+                scannedFiles.push(manifestPath);
+                try {
+                    const text = readFileSync(manifestPath, 'utf-8');
+                    const r = scanText(text, allowlist);
+                    for (const rej of r.rejections)
+                        rejections.push(`${eco.manifest}: ${rej}`);
+                }
+                catch (err) {
+                    warnings.push(`could not read ${eco.manifest}: ${err.message}`);
+                }
+            }
+        }
+        // Scan lockfile content too — that's where transitive hostile URLs hide.
+        // Binary lockfiles (bun.lockb) are skipped: their text has no URL strings
+        // readable via regex. Consumers should migrate to bun.lock (text format).
+        if (eco.lockfile && eco.lockfile !== 'bun.lockb') {
+            const lockPath = join(worktreePath, eco.lockfile);
+            if (existsSync(lockPath)) {
+                scannedFiles.push(lockPath);
+                try {
+                    const text = readFileSync(lockPath, 'utf-8');
+                    const r = scanText(text, allowlist);
+                    for (const rej of r.rejections)
+                        rejections.push(`${eco.lockfile}: ${rej}`);
+                }
+                catch (err) {
+                    warnings.push(`could not read ${eco.lockfile}: ${err.message}`);
+                }
+            }
+        }
+        // Surface the ecosystem-level warning (bun.lockb-only) as a scanner
+        // warning so it lands in the install log.
+        if (eco.warning)
+            warnings.push(`${eco.ecosystem}: ${eco.warning}`);
+    }
+    return {
+        ok: rejections.length === 0,
+        warnings,
+        rejections,
+        scanned_files: scannedFiles,
+    };
+}
+//# sourceMappingURL=manifest-scanner.mjs.map

package/dist/cli/install/manifest-scanner.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-scanner.mjs","sourceRoot":"","sources":["../../../src/cli/install/manifest-scanner.mjs"],"names":[],"mappings":"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"}

package/dist/cli/install/manifest.d.mts

@@ -0,0 +1,85 @@
+/**
+ * @typedef {Object} ManifestFileEntry
+ * @property {string} path
+ * @property {string} sourceHash
+ * @property {string} installedHash
+ * @property {string} sourcePath
+ * @property {string} transformVersion
+ */
+/**
+ * @typedef {Object} Manifest
+ * @property {number} version
+ * @property {string} installed_at
+ * @property {string} runtime
+ * @property {string} framework_version
+ * @property {ManifestFileEntry[]} files
+ */
+/**
+ * Compute a sha256 hex digest for a string or buffer.
+ *
+ * @param {string|Buffer} data
+ * @returns {string}
+ */
+export function sha256(data: string | Buffer): string;
+/**
+ * Build a fresh manifest object. Files start empty — the pipeline appends
+ * via `addManifestEntry` as it writes outputs.
+ *
+ * @param {{ runtime: string, frameworkVersion: string }} args
+ * @returns {Manifest}
+ */
+export function newManifest({ runtime, frameworkVersion }: {
+    runtime: string;
+    frameworkVersion: string;
+}): Manifest;
+/**
+ * Append a file entry to a manifest. Mutates in place + returns the
+ * manifest for chaining.
+ *
+ * @param {Manifest} manifest
+ * @param {ManifestFileEntry} entry
+ * @returns {Manifest}
+ */
+export function addManifestEntry(manifest: Manifest, entry: ManifestFileEntry): Manifest;
+/**
+ * Atomically persist a manifest under `<installRoot>/apt-file-manifest.json`.
+ * Reuses the framework's atomicWriteJson (tmp + fsync + rename) so partial
+ * writes are not observable.
+ *
+ * @param {string} installRoot
+ * @param {Manifest} manifest
+ */
+export function writeManifest(installRoot: string, manifest: Manifest): void;
+/**
+ * Load a manifest from disk. Returns null when missing or unreadable
+ * (callers decide whether that's an error).
+ *
+ * @param {string} installRoot
+ * @returns {Manifest|null}
+ */
+export function readManifest(installRoot: string): Manifest | null;
+/**
+ * Sanity-check a parsed manifest. Returns an array of human-readable
+ * error strings; empty array means valid.
+ *
+ * @param {unknown} m
+ * @returns {string[]}
+ */
+export function validateManifest(m: unknown): string[];
+export const MANIFEST_FILENAME: "apt-file-manifest.json";
+export const MANIFEST_SCHEMA_VERSION: 1;
+export type ManifestFileEntry = {
+    path: string;
+    sourceHash: string;
+    installedHash: string;
+    sourcePath: string;
+    transformVersion: string;
+};
+export type Manifest = {
+    version: number;
+    installed_at: string;
+    runtime: string;
+    framework_version: string;
+    files: ManifestFileEntry[];
+};
+//# sourceMappingURL=manifest.d.mts.map

package/dist/cli/install/manifest.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.mts","sourceRoot":"","sources":["../../../src/cli/install/manifest.mjs"],"names":[],"mappings":"AAkCA;;;;;;;GAOG;AAEH;;;;;;;GAOG;AAEH;;;;;GAKG;AACH,6BAHW,MAAM,GAAC,MAAM,GACX,MAAM,CAIlB;AAED;;;;;;GAMG;AACH,2DAHW;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAA;CAAE,GAC3C,QAAQ,CAUpB;AAED;;;;;;;GAOG;AACH,2CAJW,QAAQ,SACR,iBAAiB,GACf,QAAQ,CAKpB;AAED;;;;;;;GAOG;AACH,2CAHW,MAAM,YACN,QAAQ,QAIlB;AAED;;;;;;GAMG;AACH,0CAHW,MAAM,GACJ,QAAQ,GAAC,IAAI,CAezB;AAED;;;;;;GAMG;AACH,oCAHW,OAAO,GACL,MAAM,EAAE,CA2BpB;AA/HD,gCAAiC,wBAAwB,CAAA;AACzD,sCAAuC,CAAC,CAAA;;UAI1B,MAAM;gBACN,MAAM;mBACN,MAAM;gBACN,MAAM;sBACN,MAAM;;;aAKN,MAAM;kBACN,MAAM;aACN,MAAM;uBACN,MAAM;WACN,iBAAiB,EAAE"}

package/dist/cli/install/manifest.mjs

@@ -0,0 +1,161 @@
+/**
+ * install/manifest.mjs — read/write/validate `apt-file-manifest.json`.
+ *
+ * One manifest is written per runtime install root (e.g.
+ * `.claude/apt-file-manifest.json`, `.cursor/apt-file-manifest.json`). The
+ * manifest is the authoritative record of what the installer wrote for that
+ * runtime — `check-version` walks it to detect drift.
+ *
+ * Schema:
+ *   {
+ *     version: 1,                       // manifest schema version
+ *     installed_at: ISO8601,
+ *     runtime: 'claude' | 'cursor' | ...,
+ *     framework_version: '0.1.0',
+ *     files: [
+ *       {
+ *         path: 'skills/apt-foo/SKILL.md',   // relative to install root
+ *         sourceHash: '<sha256 of canonical pre-transform>',
+ *         installedHash: '<sha256 of post-transform output>',
+ *         sourcePath: 'packages/framework/skills/apt-foo/SKILL.md',
+ *         transformVersion: '1'
+ *       }
+ *     ]
+ *   }
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { atomicWriteJson } from '../util/atomic-write.mjs';
+export const MANIFEST_FILENAME = 'apt-file-manifest.json';
+export const MANIFEST_SCHEMA_VERSION = 1;
+/**
+ * @typedef {Object} ManifestFileEntry
+ * @property {string} path
+ * @property {string} sourceHash
+ * @property {string} installedHash
+ * @property {string} sourcePath
+ * @property {string} transformVersion
+ */
+/**
+ * @typedef {Object} Manifest
+ * @property {number} version
+ * @property {string} installed_at
+ * @property {string} runtime
+ * @property {string} framework_version
+ * @property {ManifestFileEntry[]} files
+ */
+/**
+ * Compute a sha256 hex digest for a string or buffer.
+ *
+ * @param {string|Buffer} data
+ * @returns {string}
+ */
+export function sha256(data) {
+    return createHash('sha256').update(data).digest('hex');
+}
+/**
+ * Build a fresh manifest object. Files start empty — the pipeline appends
+ * via `addManifestEntry` as it writes outputs.
+ *
+ * @param {{ runtime: string, frameworkVersion: string }} args
+ * @returns {Manifest}
+ */
+export function newManifest({ runtime, frameworkVersion }) {
+    return {
+        version: MANIFEST_SCHEMA_VERSION,
+        installed_at: new Date().toISOString(),
+        runtime,
+        framework_version: frameworkVersion,
+        files: [],
+    };
+}
+/**
+ * Append a file entry to a manifest. Mutates in place + returns the
+ * manifest for chaining.
+ *
+ * @param {Manifest} manifest
+ * @param {ManifestFileEntry} entry
+ * @returns {Manifest}
+ */
+export function addManifestEntry(manifest, entry) {
+    manifest.files.push(entry);
+    return manifest;
+}
+/**
+ * Atomically persist a manifest under `<installRoot>/apt-file-manifest.json`.
+ * Reuses the framework's atomicWriteJson (tmp + fsync + rename) so partial
+ * writes are not observable.
+ *
+ * @param {string} installRoot
+ * @param {Manifest} manifest
+ */
+export function writeManifest(installRoot, manifest) {
+    atomicWriteJson(join(installRoot, MANIFEST_FILENAME), manifest);
+}
+/**
+ * Load a manifest from disk. Returns null when missing or unreadable
+ * (callers decide whether that's an error).
+ *
+ * @param {string} installRoot
+ * @returns {Manifest|null}
+ */
+export function readManifest(installRoot) {
+    const path = join(installRoot, MANIFEST_FILENAME);
+    if (!existsSync(path))
+        return null;
+    try {
+        const data = JSON.parse(readFileSync(path, 'utf-8'));
+        if (typeof data !== 'object' || data === null)
+            return null;
+        if (typeof data.runtime !== 'string')
+            return null;
+        if (typeof data.framework_version !== 'string')
+            return null;
+        if (!Array.isArray(data.files))
+            return null;
+        return /** @type {Manifest} */ (data);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Sanity-check a parsed manifest. Returns an array of human-readable
+ * error strings; empty array means valid.
+ *
+ * @param {unknown} m
+ * @returns {string[]}
+ */
+export function validateManifest(m) {
+    const errors = [];
+    if (typeof m !== 'object' || m === null) {
+        return ['manifest is not an object'];
+    }
+    const obj = /** @type {Record<string, unknown>} */ (m);
+    if (typeof obj.version !== 'number')
+        errors.push('missing or invalid `version`');
+    if (typeof obj.runtime !== 'string')
+        errors.push('missing or invalid `runtime`');
+    if (typeof obj.framework_version !== 'string')
+        errors.push('missing `framework_version`');
+    if (typeof obj.installed_at !== 'string')
+        errors.push('missing `installed_at`');
+    if (!Array.isArray(obj.files)) {
+        errors.push('missing `files` array');
+        return errors;
+    }
+    for (const [i, f] of obj.files.entries()) {
+        if (typeof f !== 'object' || f === null) {
+            errors.push(`files[${i}] is not an object`);
+            continue;
+        }
+        const fe = /** @type {Record<string, unknown>} */ (f);
+        for (const k of ['path', 'sourceHash', 'installedHash', 'sourcePath', 'transformVersion']) {
+            if (typeof fe[k] !== 'string')
+                errors.push(`files[${i}].${k} missing or not string`);
+        }
+    }
+    return errors;
+}
+//# sourceMappingURL=manifest.mjs.map

package/dist/cli/install/manifest.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.mjs","sourceRoot":"","sources":["../../../src/cli/install/manifest.mjs"],"names":[],"mappings":"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"}

package/dist/cli/install/pipeline.d.mts

@@ -0,0 +1,104 @@
+/**
+ * @typedef {Object} CanonicalFile
+ * @property {string} canonicalPath  absolute path to the canonical source
+ * @property {string} relPath         path relative to packages/framework (used in manifest sourcePath)
+ * @property {'skill'|'agent'|'hook-js'|'hook-sh'|'unknown'} fileType
+ * @property {string} content
+ */
+/**
+ * @typedef {Object} TransformOutput
+ * @property {string} outputPath  path relative to the runtime's install root
+ * @property {string} content
+ */
+/**
+ * @typedef {Object} TransformInput
+ * @property {string} canonicalContent
+ * @property {string} canonicalPath
+ * @property {string} canonicalRelPath
+ * @property {string} version
+ * @property {'skill'|'agent'|'hook-js'|'hook-sh'|'unknown'} fileType
+ */
+/**
+ * @typedef {(input: TransformInput) => TransformOutput[]} TransformFn
+ */
+/**
+ * Discover canonical input files under `packages/framework/`. Returns
+ * skills (`skills/<name>/SKILL.md`, `skills/apt-*.md`) and agents
+ * (`agents/apt-*.md`). Hooks (`hooks/*.js`) are included when the dir
+ * exists.
+ *
+ * @param {string} canonicalRoot  absolute path to packages/framework
+ * @returns {CanonicalFile[]}
+ */
+export function discoverCanonicalFiles(canonicalRoot: string): CanonicalFile[];
+/**
+ * Run the install pipeline for a single runtime. Discovers canonical files,
+ * runs the runtime's transform on each, writes outputs, writes manifest.
+ *
+ * @param {Object} args
+ * @param {string} args.runtime         runtime id (e.g. 'claude')
+ * @param {TransformFn} args.transform  transform function from the runtime module
+ * @param {string} args.canonicalRoot   absolute path to packages/framework
+ * @param {string} args.targetDir       absolute path to the project root the user is installing into
+ * @param {string} args.version         framework version string (replaces {{APT_VERSION}})
+ * @param {CanonicalFile[]} [args.canonicalFiles]  pre-discovered files (pass to avoid redundant disk reads when installing multiple runtimes)
+ * @returns {{ runtime: string, installRoot: string, files: string[], skipped: string[], manifest: import('./manifest.mjs').Manifest }}
+ */
+export function runInstall({ runtime, transform, canonicalRoot, targetDir, version, canonicalFiles, }: {
+    runtime: string;
+    transform: TransformFn;
+    canonicalRoot: string;
+    targetDir: string;
+    version: string;
+    canonicalFiles?: CanonicalFile[] | undefined;
+}): {
+    runtime: string;
+    installRoot: string;
+    files: string[];
+    skipped: string[];
+    manifest: import("./manifest.mjs").Manifest;
+};
+/**
+ * Write a top-level summary of the install (which runtimes were installed,
+ * counts) to `.aperant/install/last-install.json` for cross-runtime
+ * visibility. Used by `init` to record the multi-runtime decision once.
+ *
+ * @param {string} targetDir
+ * @param {Array<{ runtime: string, installRoot: string, files: string[], skipped: string[] }>} results
+ * @param {string} version
+ */
+export function writeLastInstallSummary(targetDir: string, results: Array<{
+    runtime: string;
+    installRoot: string;
+    files: string[];
+    skipped: string[];
+}>, version: string): void;
+export const __pipelineDirname: string;
+export type CanonicalFile = {
+    /**
+     * absolute path to the canonical source
+     */
+    canonicalPath: string;
+    /**
+     * path relative to packages/framework (used in manifest sourcePath)
+     */
+    relPath: string;
+    fileType: "skill" | "agent" | "hook-js" | "hook-sh" | "unknown";
+    content: string;
+};
+export type TransformOutput = {
+    /**
+     * path relative to the runtime's install root
+     */
+    outputPath: string;
+    content: string;
+};
+export type TransformInput = {
+    canonicalContent: string;
+    canonicalPath: string;
+    canonicalRelPath: string;
+    version: string;
+    fileType: "skill" | "agent" | "hook-js" | "hook-sh" | "unknown";
+};
+export type TransformFn = (input: TransformInput) => TransformOutput[];
+//# sourceMappingURL=pipeline.d.mts.map

package/dist/cli/install/pipeline.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.d.mts","sourceRoot":"","sources":["../../../src/cli/install/pipeline.mjs"],"names":[],"mappings":"AAgDA;;;;;;GAMG;AAEH;;;;GAIG;AAEH;;;;;;;GAOG;AAEH;;GAEG;AAEH;;;;;;;;GAQG;AACH,sDAHW,MAAM,GACJ,aAAa,EAAE,CAmE3B;AAED;;;;;;;;;;;;GAYG;AACH,uGARG;IAAqB,OAAO,EAApB,MAAM;IACY,SAAS,EAA3B,WAAW;IACE,aAAa,EAA1B,MAAM;IACO,SAAS,EAAtB,MAAM;IACO,OAAO,EAApB,MAAM;IACiB,cAAc;CAC7C,GAAU;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,OAAO,gBAAgB,EAAE,QAAQ,CAAA;CAAE,CAmFrI;AAED;;;;;;;;GAQG;AACH,mDAJW,MAAM,WACN,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,WACnF,MAAM,QAehB;AAmBD,uCAAwE;;;;;mBA9O1D,MAAM;;;;aACN,MAAM;cACN,OAAO,GAAC,OAAO,GAAC,SAAS,GAAC,SAAS,GAAC,SAAS;aAC7C,MAAM;;;;;;gBAKN,MAAM;aACN,MAAM;;;sBAKN,MAAM;mBACN,MAAM;sBACN,MAAM;aACN,MAAM;cACN,OAAO,GAAC,OAAO,GAAC,SAAS,GAAC,SAAS,GAAC,SAAS;;0BAI9C,CAAC,KAAK,EAAE,cAAc,KAAK,eAAe,EAAE"}