linkany 0.0.1 → 0.0.3

package/README.md

@@ -90,7 +90,16 @@
 
 ## API
 
-### `add(manifestPath, { source, target, kind?, atomic? }, opts?)`
+`linkany` 的 API 支持两种输入方式，合并为同一个入口：
+
+- **文件模式**：`manifest` 传入 manifest 文件路径（string）
+- **in-memory 模式**：`manifest` 直接传入 manifest JSON/对象
+
+四个核心 API 的返回值统一为：
+
+- `{ result, manifest }`（`result` 为本次操作结果，`manifest` 为操作后的 manifest 对象）
+
+### `add(manifest, { source, target, kind?, atomic? }, opts?)`
 
 用途：把一条映射写入 manifest，并把 `target` 收敛为指向 `source` 的 symlink。
 
@@ -103,7 +112,7 @@
   - 再把 `target` 改成指向 `source` 的 symlink
 - **source 与 target 同时存在**：拒绝（error），要求用户手动处理冲突。
 
-### `remove(manifestPath, key, opts?)`
+### `remove(manifest, key, opts?)`
 
 用途：从 manifest 移除一条映射，并且 **默认删除 target 的 symlink**。
 
@@ -111,7 +120,7 @@
 - `opts.keepLink=true` 可仅移除 manifest 记录，不删除 target symlink。
 - **永远不删除 source**。
 
-### `install(manifestPath, opts?)`
+### `install(manifest, opts?)`
 
 用途：按 manifest 全量落地，确保每个 `target` 都是指向 `source` 的 symlink。
 
@@ -121,15 +130,23 @@
   - source 不存在
   - target 存在但不是 symlink
 
-### `uninstall(manifestPath, opts?)`
+### `uninstall(manifest, opts?)`
 
 用途：按 manifest 全量撤销，只删除 `target` 的 symlink；**永远不删除 source**。
 
+### in-memory 模式的额外 options
+
+当 `manifest` 传入 JSON/对象（而不是路径）时，`opts` 额外支持：
+
+- `baseDir?: string`：用于解析相对路径（默认 `process.cwd()`）
+- `manifestPath?: string`：仅用于 `Result.manifestPath` 与 audit 默认路径推导（不会触发读写 manifest 文件）
+
 ## 审计日志（Audit Log）
 
 - 默认写入：`${manifestPath}.log.jsonl`
 - 每行是一条 JSON（完整 `Result`），包含：执行步骤、错误、耗时、变更摘要。
 - 可通过 `opts.auditLogPath` 指定自定义路径。
+- 如需完全关闭审计（由上层自行处理），传 `opts.audit=false`；CLI 对应 `--no-audit`。
 
 ## Options（opts）
 

package/dist/api/add.d.ts

@@ -1,4 +1,6 @@
+import type { Manifest } from '../manifest/types.js';
 import { CommonOptions, LinkKind, Result } from '../types.js';
+import type { ManifestInputOptions } from './manifest-input.js';
 export interface Mapping {
     source: string;
     target: string;
@@ -14,4 +16,9 @@ export interface Mapping {
  *   copy(target -> source), move original target aside to backup, then link target -> source.
  * - If symlink creation fails => error (no copy fallback).
  */
-export declare function add(manifestPath: string, mapping: Mapping, opts?: CommonOptions): Promise<Result>;
+export interface AddOptions extends CommonOptions, ManifestInputOptions {
+}
+export declare function add(manifest: string | unknown, mapping: Mapping, opts?: AddOptions): Promise<{
+    result: Result;
+    manifest: Manifest;
+}>;

package/dist/api/add.js

@@ -5,6 +5,7 @@ import { planReplaceTargetWithTmp } from '../core/backup.js';
 import { detectKind, isSymlinkTo, planCopy, planEnsureSource, planUnlink, tmpPathForTarget } from '../core/plan.js';
 import { getManifestBaseDir } from '../manifest/types.js';
 import { loadOrCreateManifest, saveManifest, upsertEntry } from '../manifest/io.js';
+import { normalizeManifestJson, resolveBaseDir } from './manifest-input.js';
 function mkLogger(opts) {
     return opts?.logger;
 }
@@ -33,26 +34,21 @@ function linkSteps(sourceAbs, targetAbs, kind, atomic) {
     }
     return steps;
 }
-/**
- * add: write manifest + converge target to symlink(source).
- *
- * Safety rules:
- * - If source and target both exist AND target is not already a symlink to source => reject.
- * - If target exists and is not a symlink AND source is missing => migrate:
- *   copy(target -> source), move original target aside to backup, then link target -> source.
- * - If symlink creation fails => error (no copy fallback).
- */
-export async function add(manifestPath, mapping, opts) {
+export async function add(manifest, mapping, opts) {
+    if (typeof manifest === 'string') {
+        return await addFromPath(manifest, mapping, opts);
+    }
+    return await addFromJson(manifest, mapping, opts);
+}
+async function addFromPath(manifestPath, mapping, opts) {
     const baseDir = getManifestBaseDir(manifestPath);
     const sourceAbs = path.isAbsolute(mapping.source) ? mapping.source : path.resolve(baseDir, mapping.source);
     const targetAbs = path.isAbsolute(mapping.target) ? mapping.target : path.resolve(baseDir, mapping.target);
-    const sourceExists = await fs.pathExists(sourceAbs);
-    const targetExists = await fs.pathExists(targetAbs);
     if (await isSymlinkTo(targetAbs, sourceAbs)) {
         const manifest = await loadOrCreateManifest(manifestPath);
         upsertEntry(manifest, { source: mapping.source, target: mapping.target, kind: mapping.kind, atomic: mapping.atomic });
         await saveManifest(manifestPath, manifest);
-        return await runOperation({
+        const result = await runOperation({
             operation: 'add',
             manifestPath,
             steps: [],
@@ -63,23 +59,28 @@ export async function add(manifestPath, mapping, opts) {
                 return res;
             },
         });
+        return { result, manifest };
     }
+    const sourceExists = await fs.pathExists(sourceAbs);
+    const targetExists = await fs.pathExists(targetAbs);
     if (sourceExists && targetExists) {
+        const current = await loadOrCreateManifest(manifestPath);
         const res = mkResult('add', manifestPath);
         res.ok = false;
         res.errors.push(`Refusing to proceed: source and target both exist: source=${sourceAbs} target=${targetAbs}`);
         res.steps.push({ kind: 'noop', message: 'Safety refusal', status: 'failed', error: res.errors[0] });
-        return res;
+        return { result: res, manifest: current };
     }
     let kind = mapping.kind ?? 'file';
     if (targetExists) {
         const st = await fs.lstat(targetAbs);
         if (st.isSymbolicLink()) {
-            let res = mkResult('add', manifestPath);
+            const current = await loadOrCreateManifest(manifestPath);
+            const res = mkResult('add', manifestPath);
             res.ok = false;
             res.errors.push(`Refusing to migrate: target is an existing symlink: ${targetAbs}`);
             res.steps.push({ kind: 'noop', message: 'Safety refusal', status: 'failed', error: res.errors[0] });
-            return res;
+            return { result: res, manifest: current };
         }
         kind = st.isDirectory() ? 'dir' : 'file';
     }
@@ -104,7 +105,7 @@ export async function add(manifestPath, mapping, opts) {
     }
     const manifest = await loadOrCreateManifest(manifestPath);
     upsertEntry(manifest, { source: mapping.source, target: mapping.target, kind: kind, atomic });
-    return await runOperation({
+    const result = await runOperation({
         operation: 'add',
         manifestPath,
         steps,
@@ -126,4 +127,115 @@ export async function add(manifestPath, mapping, opts) {
             return res;
         },
     });
+    return { result, manifest };
+}
+async function addFromJson(manifestJson, mapping, opts) {
+    const manifest = normalizeManifestJson(manifestJson);
+    const baseDir = resolveBaseDir(opts);
+    const sourceAbs = path.isAbsolute(mapping.source) ? mapping.source : path.resolve(baseDir, mapping.source);
+    const targetAbs = path.isAbsolute(mapping.target) ? mapping.target : path.resolve(baseDir, mapping.target);
+    const sourceExists = await fs.pathExists(sourceAbs);
+    const targetExists = await fs.pathExists(targetAbs);
+    if (await isSymlinkTo(targetAbs, sourceAbs)) {
+        upsertEntry(manifest, { source: mapping.source, target: mapping.target, kind: mapping.kind, atomic: mapping.atomic });
+        const result = await runOperation({
+            operation: 'add',
+            manifestPath: opts?.manifestPath,
+            steps: [],
+            opts,
+            finalize: async (res) => {
+                res.steps.push({ kind: 'write_manifest', message: 'In-memory manifest; not writing to disk', status: 'skipped' });
+                res.changes.push({ action: 'manifest_upsert', source: sourceAbs, target: targetAbs });
+                return res;
+            },
+        });
+        return { result, manifest };
+    }
+    if (sourceExists && targetExists) {
+        const now = new Date().toISOString();
+        const res = {
+            ok: false,
+            operation: 'add',
+            manifestPath: opts?.manifestPath,
+            startedAt: now,
+            finishedAt: now,
+            durationMs: 0,
+            steps: [{ kind: 'noop', message: 'Safety refusal', status: 'failed', error: `Refusing to proceed: source and target both exist: source=${sourceAbs} target=${targetAbs}` }],
+            warnings: [],
+            errors: [`Refusing to proceed: source and target both exist: source=${sourceAbs} target=${targetAbs}`],
+            changes: [],
+        };
+        return { result: res, manifest };
+    }
+    let kind = mapping.kind ?? 'file';
+    if (targetExists) {
+        const st = await fs.lstat(targetAbs);
+        if (st.isSymbolicLink()) {
+            const now = new Date().toISOString();
+            const res = {
+                ok: false,
+                operation: 'add',
+                manifestPath: opts?.manifestPath,
+                startedAt: now,
+                finishedAt: now,
+                durationMs: 0,
+                steps: [{ kind: 'noop', message: 'Safety refusal', status: 'failed', error: `Refusing to migrate: target is an existing symlink: ${targetAbs}` }],
+                warnings: [],
+                errors: [`Refusing to migrate: target is an existing symlink: ${targetAbs}`],
+                changes: [],
+            };
+            return { result: res, manifest };
+        }
+        kind = st.isDirectory() ? 'dir' : 'file';
+    }
+    else if (sourceExists) {
+        kind = await detectKind(sourceAbs);
+    }
+    const atomic = mapping.atomic ?? true;
+    const steps = [];
+    if (!sourceExists && targetExists) {
+        steps.push(...await planCopy({ fromAbs: targetAbs, toAbs: sourceAbs, kind, atomic }));
+        // Move original target to backup, then put symlink into place.
+        const { steps: replaceSteps } = planReplaceTargetWithTmp({ targetAbs, atomic: true });
+        steps.push(...replaceSteps.slice(0, 1)); // move target -> backup
+        steps.push(...(function linkSteps(sourceAbs, targetAbs, kind, atomic) {
+            const s = [];
+            s.push({ kind: 'mkdirp', message: 'Ensure target parent directory exists', paths: { dir: path.dirname(targetAbs) } });
+            const tmp = atomic ? tmpPathForTarget(targetAbs) : targetAbs;
+            s.push({ kind: 'symlink', message: atomic ? 'Create symlink at temp path' : 'Create symlink', paths: { source: sourceAbs, target: tmp, kind } });
+            if (atomic)
+                s.push({ kind: 'move', message: 'Atomically move temp symlink into place', paths: { from: tmp, to: targetAbs } });
+            return s;
+        })(sourceAbs, targetAbs, kind, atomic));
+    }
+    else {
+        steps.push(...await planEnsureSource({ sourceAbs, kind }));
+        if (targetExists) {
+            steps.push(...await planUnlink({ targetAbs }));
+        }
+        steps.push(...(function linkSteps(sourceAbs, targetAbs, kind, atomic) {
+            const s = [];
+            s.push({ kind: 'mkdirp', message: 'Ensure target parent directory exists', paths: { dir: path.dirname(targetAbs) } });
+            const tmp = atomic ? tmpPathForTarget(targetAbs) : targetAbs;
+            s.push({ kind: 'symlink', message: atomic ? 'Create symlink at temp path' : 'Create symlink', paths: { source: sourceAbs, target: tmp, kind } });
+            if (atomic)
+                s.push({ kind: 'move', message: 'Atomically move temp symlink into place', paths: { from: tmp, to: targetAbs } });
+            return s;
+        })(sourceAbs, targetAbs, kind, atomic));
+    }
+    upsertEntry(manifest, { source: mapping.source, target: mapping.target, kind: kind, atomic });
+    const result = await runOperation({
+        operation: 'add',
+        manifestPath: opts?.manifestPath,
+        steps,
+        opts,
+        finalize: async (res) => {
+            if (!res.ok)
+                return res;
+            res.steps.push({ kind: 'write_manifest', message: 'In-memory manifest; not writing to disk', status: 'skipped' });
+            res.changes.push({ action: 'manifest_upsert', source: sourceAbs, target: targetAbs });
+            return res;
+        },
+    });
+    return { result, manifest };
 }

package/dist/api/install.d.ts

@@ -1,6 +1,13 @@
+import type { Manifest } from '../manifest/types.js';
 import { CommonOptions, Result } from '../types.js';
+import type { ManifestInputOptions } from './manifest-input.js';
 /**
  * Ensure all targets are symlinks to sources. Never mutates manifest.
  * Safety: if any target exists and is not a symlink, abort without changes.
  */
-export declare function install(manifestPath: string, opts?: CommonOptions): Promise<Result>;
+export interface InstallOptions extends CommonOptions, ManifestInputOptions {
+}
+export declare function install(manifest: string | unknown, opts?: InstallOptions): Promise<{
+    result: Result;
+    manifest: Manifest;
+}>;

package/dist/api/install.js

@@ -4,6 +4,7 @@ import { planReplaceTargetWithTmp } from '../core/backup.js';
 import { runOperation } from '../core/runner.js';
 import { detectKind, isSymlinkTo, tmpPathForTarget } from '../core/plan.js';
 import { getManifestBaseDir, loadManifest, resolveEntry } from '../manifest/types.js';
+import { normalizeManifestJson, resolveBaseDir } from './manifest-input.js';
 function mkLogger(opts) {
     return opts?.logger;
 }
@@ -32,11 +33,13 @@ function linkSteps(sourceAbs, targetAbs, kind, atomic) {
     }
     return steps;
 }
-/**
- * Ensure all targets are symlinks to sources. Never mutates manifest.
- * Safety: if any target exists and is not a symlink, abort without changes.
- */
-export async function install(manifestPath, opts) {
+export async function install(manifest, opts) {
+    if (typeof manifest === 'string') {
+        return await installFromPath(manifest, opts);
+    }
+    return await installFromJson(manifest, opts);
+}
+async function installFromPath(manifestPath, opts) {
     const logger = mkLogger(opts);
     const result = await (async () => {
         const manifest = await loadManifest(manifestPath);
@@ -49,7 +52,7 @@ export async function install(manifestPath, opts) {
                 res.ok = false;
                 res.errors.push(`Source missing: ${r.sourceAbs}`);
                 res.steps.push({ kind: 'noop', message: 'Source missing; aborting without changes', status: 'failed', error: res.errors[0], paths: { source: r.sourceAbs } });
-                return res;
+                return { result: res, manifest };
             }
             const targetExists = await fs.pathExists(r.targetAbs);
             if (targetExists) {
@@ -59,7 +62,7 @@ export async function install(manifestPath, opts) {
                     res.ok = false;
                     res.errors.push(`Conflict: target exists and is not a symlink: ${r.targetAbs}`);
                     res.steps.push({ kind: 'noop', message: 'Conflict detected; aborting without changes', status: 'failed', error: res.errors[0], paths: { target: r.targetAbs } });
-                    return res;
+                    return { result: res, manifest };
                 }
             }
             const kind = r.kind ?? await detectKind(r.sourceAbs);
@@ -77,12 +80,60 @@ export async function install(manifestPath, opts) {
             }
             allSteps.push(...linkSteps(r.sourceAbs, r.targetAbs, kind, r.atomic));
         }
-        return await runOperation({
+        const result = await runOperation({
             operation: 'install',
             manifestPath,
             steps: allSteps,
             opts,
         });
+        return { result, manifest };
     })();
+    logger; // keep logger referenced (existing pattern)
     return result;
 }
+async function installFromJson(manifestJson, opts) {
+    const manifest = normalizeManifestJson(manifestJson);
+    const baseDir = resolveBaseDir(opts);
+    const allSteps = [];
+    for (const entry of manifest.installs) {
+        const r = resolveEntry(baseDir, entry);
+        if (!await fs.pathExists(r.sourceAbs)) {
+            const res = mkResult('install', opts?.manifestPath);
+            res.ok = false;
+            res.errors.push(`Source missing: ${r.sourceAbs}`);
+            res.steps.push({ kind: 'noop', message: 'Source missing; aborting without changes', status: 'failed', error: res.errors[0], paths: { source: r.sourceAbs } });
+            return { result: res, manifest };
+        }
+        const targetExists = await fs.pathExists(r.targetAbs);
+        if (targetExists) {
+            const st = await fs.lstat(r.targetAbs);
+            if (!st.isSymbolicLink()) {
+                const res = mkResult('install', opts?.manifestPath);
+                res.ok = false;
+                res.errors.push(`Conflict: target exists and is not a symlink: ${r.targetAbs}`);
+                res.steps.push({ kind: 'noop', message: 'Conflict detected; aborting without changes', status: 'failed', error: res.errors[0], paths: { target: r.targetAbs } });
+                return { result: res, manifest };
+            }
+        }
+        const kind = r.kind ?? await detectKind(r.sourceAbs);
+        if (await isSymlinkTo(r.targetAbs, r.sourceAbs))
+            continue;
+        if (targetExists) {
+            if (r.atomic) {
+                const { steps: replaceSteps } = planReplaceTargetWithTmp({ targetAbs: r.targetAbs, atomic: true });
+                allSteps.push(...replaceSteps.slice(0, 1));
+            }
+            else {
+                allSteps.push({ kind: 'unlink', message: 'Remove existing target symlink before linking', paths: { target: r.targetAbs } });
+            }
+        }
+        allSteps.push(...linkSteps(r.sourceAbs, r.targetAbs, kind, r.atomic));
+    }
+    const result = await runOperation({
+        operation: 'install',
+        manifestPath: opts?.manifestPath,
+        steps: allSteps,
+        opts,
+    });
+    return { result, manifest };
+}

package/dist/api/manifest-input.d.ts

@@ -0,0 +1,16 @@
+import { Manifest } from '../manifest/types.js';
+export interface ManifestInputOptions {
+    /**
+     * Base dir for resolving relative paths in manifest entries / mappings.
+     * Default: process.cwd()
+     */
+    baseDir?: string;
+    /**
+     * Optional manifestPath for observability/audit only.
+     * - If provided, it will be set on Result.manifestPath.
+     * - If opts.auditLogPath is NOT provided, audit default path will use this manifestPath.
+     */
+    manifestPath?: string;
+}
+export declare function normalizeManifestJson(raw: unknown): Manifest;
+export declare function resolveBaseDir(opts?: ManifestInputOptions): string;

package/dist/api/manifest-input.js

@@ -0,0 +1,8 @@
+import path from 'path';
+import { normalizeManifest } from '../manifest/types.js';
+export function normalizeManifestJson(raw) {
+    return normalizeManifest(raw);
+}
+export function resolveBaseDir(opts) {
+    return path.resolve(opts?.baseDir ?? process.cwd());
+}

package/dist/api/remove.d.ts

@@ -1,4 +1,6 @@
+import type { Manifest } from '../manifest/types.js';
 import { CommonOptions, Result } from '../types.js';
+import type { ManifestInputOptions } from './manifest-input.js';
 export interface RemoveOptions extends CommonOptions {
     /**
      * Default: false. If true, do NOT delete the target link.
@@ -9,4 +11,9 @@ export interface RemoveOptions extends CommonOptions {
  * remove: remove an entry from manifest, and by default delete the target symlink.
  * Never deletes sources.
  */
-export declare function remove(manifestPath: string, key: string, opts?: RemoveOptions): Promise<Result>;
+export interface RemoveUnifiedOptions extends RemoveOptions, ManifestInputOptions {
+}
+export declare function remove(manifest: string | unknown, key: string, opts?: RemoveUnifiedOptions): Promise<{
+    result: Result;
+    manifest: Manifest;
+}>;

package/dist/api/remove.js

@@ -3,29 +3,36 @@ import { runOperation } from '../core/runner.js';
 import { planUnlink } from '../core/plan.js';
 import { getManifestBaseDir, loadManifest, resolveEntry } from '../manifest/types.js';
 import { removeEntry, saveManifest } from '../manifest/io.js';
+import { normalizeManifestJson, resolveBaseDir } from './manifest-input.js';
 function mkLogger(opts) {
     return opts?.logger;
 }
-/**
- * remove: remove an entry from manifest, and by default delete the target symlink.
- * Never deletes sources.
- */
-export async function remove(manifestPath, key, opts) {
+export async function remove(manifest, key, opts) {
+    if (typeof manifest === 'string') {
+        return await removeFromPath(manifest, key, opts);
+    }
+    return await removeFromJson(manifest, key, opts);
+}
+async function removeFromPath(manifestPath, key, opts) {
     const manifest = await loadManifest(manifestPath);
     const baseDir = getManifestBaseDir(manifestPath);
     const entry = manifest.installs.find(e => (e.id && e.id === key) || e.target === key || (e.id || e.target) === key);
     if (!entry) {
+        const now = new Date().toISOString();
         return {
-            ok: false,
-            operation: 'remove',
-            manifestPath,
-            startedAt: new Date().toISOString(),
-            finishedAt: new Date().toISOString(),
-            durationMs: 0,
-            steps: [],
-            warnings: [],
-            errors: [`Entry not found in manifest: ${key}`],
-            changes: [],
+            result: {
+                ok: false,
+                operation: 'remove',
+                manifestPath,
+                startedAt: now,
+                finishedAt: now,
+                durationMs: 0,
+                steps: [],
+                warnings: [],
+                errors: [`Entry not found in manifest: ${key}`],
+                changes: [],
+            },
+            manifest,
         };
     }
     const r = resolveEntry(baseDir, entry);
@@ -36,7 +43,7 @@ export async function remove(manifestPath, key, opts) {
     else {
         steps.push({ kind: 'noop', message: 'keepLink=true; not unlinking target', status: 'skipped', paths: { target: r.targetAbs } });
     }
-    return await runOperation({
+    const result = await runOperation({
         operation: 'remove',
         manifestPath,
         steps,
@@ -59,4 +66,51 @@ export async function remove(manifestPath, key, opts) {
             return res;
         },
     });
+    return { result, manifest };
+}
+async function removeFromJson(manifestJson, key, opts) {
+    const manifest = normalizeManifestJson(manifestJson);
+    const baseDir = resolveBaseDir(opts);
+    const entry = manifest.installs.find(e => (e.id && e.id === key) || e.target === key || (e.id || e.target) === key);
+    if (!entry) {
+        const now = new Date().toISOString();
+        return {
+            result: {
+                ok: false,
+                operation: 'remove',
+                manifestPath: opts?.manifestPath,
+                startedAt: now,
+                finishedAt: now,
+                durationMs: 0,
+                steps: [],
+                warnings: [],
+                errors: [`Entry not found in manifest: ${key}`],
+                changes: [],
+            },
+            manifest,
+        };
+    }
+    const r = resolveEntry(baseDir, entry);
+    const steps = [];
+    if (!opts?.keepLink) {
+        steps.push(...await planUnlink({ targetAbs: r.targetAbs }));
+    }
+    else {
+        steps.push({ kind: 'noop', message: 'keepLink=true; not unlinking target', status: 'skipped', paths: { target: r.targetAbs } });
+    }
+    const result = await runOperation({
+        operation: 'remove',
+        manifestPath: opts?.manifestPath,
+        steps,
+        opts,
+        finalize: async (res) => {
+            if (!res.ok)
+                return res;
+            removeEntry(manifest, entry.id || entry.target);
+            res.steps.push({ kind: 'write_manifest', message: 'In-memory manifest; not writing to disk', status: 'skipped' });
+            res.changes.push({ action: 'manifest_remove', target: r.targetAbs });
+            return res;
+        },
+    });
+    return { result, manifest };
 }

package/dist/api/uninstall.d.ts

@@ -1,5 +1,12 @@
+import type { Manifest } from '../manifest/types.js';
 import { CommonOptions, Result } from '../types.js';
+import type { ManifestInputOptions } from './manifest-input.js';
 /**
  * Remove all target symlinks listed in manifest. Never deletes sources.
  */
-export declare function uninstall(manifestPath: string, opts?: CommonOptions): Promise<Result>;
+export interface UninstallOptions extends CommonOptions, ManifestInputOptions {
+}
+export declare function uninstall(manifest: string | unknown, opts?: UninstallOptions): Promise<{
+    result: Result;
+    manifest: Manifest;
+}>;

package/dist/api/uninstall.js

@@ -1,13 +1,17 @@
 import { runOperation } from '../core/runner.js';
 import { planUnlink } from '../core/plan.js';
 import { getManifestBaseDir, loadManifest, resolveEntry } from '../manifest/types.js';
+import { normalizeManifestJson, resolveBaseDir } from './manifest-input.js';
 function mkLogger(opts) {
     return opts?.logger;
 }
-/**
- * Remove all target symlinks listed in manifest. Never deletes sources.
- */
-export async function uninstall(manifestPath, opts) {
+export async function uninstall(manifest, opts) {
+    if (typeof manifest === 'string') {
+        return await uninstallFromPath(manifest, opts);
+    }
+    return await uninstallFromJson(manifest, opts);
+}
+async function uninstallFromPath(manifestPath, opts) {
     const manifest = await loadManifest(manifestPath);
     const baseDir = getManifestBaseDir(manifestPath);
     const allSteps = [];
@@ -15,10 +19,27 @@ export async function uninstall(manifestPath, opts) {
         const r = resolveEntry(baseDir, entry);
         allSteps.push(...await planUnlink({ targetAbs: r.targetAbs }));
     }
-    return await runOperation({
+    const result = await runOperation({
         operation: 'uninstall',
         manifestPath,
         steps: allSteps,
         opts,
     });
+    return { result, manifest };
+}
+async function uninstallFromJson(manifestJson, opts) {
+    const manifest = normalizeManifestJson(manifestJson);
+    const baseDir = resolveBaseDir(opts);
+    const allSteps = [];
+    for (const entry of manifest.installs) {
+        const r = resolveEntry(baseDir, entry);
+        allSteps.push(...await planUnlink({ targetAbs: r.targetAbs }));
+    }
+    const result = await runOperation({
+        operation: 'uninstall',
+        manifestPath: opts?.manifestPath,
+        steps: allSteps,
+        opts,
+    });
+    return { result, manifest };
 }

package/dist/cli.js

@@ -41,7 +41,8 @@ function parseCommonOptions(args) {
     const dryRun = hasFlag(args, ['--dry-run']);
     const includePlanText = hasFlag(args, ['--plan']);
     const auditLogPath = popFlagValue(args, ['--audit-log']);
-    return { dryRun, includePlanText, auditLogPath };
+    const audit = hasFlag(args, ['--no-audit']) ? false : undefined;
+    return { dryRun, includePlanText, auditLogPath, audit };
 }
 async function resolveManifestPath(args) {
     const m = popFlagValue(args, ['-m', '--manifest']);
@@ -61,10 +62,10 @@ Usage:
   linkany manifest show
   linkany manifest clear
 
-  linkany add --source <path> --target <path> [--kind file|dir] [--atomic|--no-atomic] [-m <manifest>] [--dry-run] [--plan]
-  linkany remove <key> [--keep-link] [-m <manifest>] [--dry-run] [--plan]
-  linkany install [-m <manifest>] [--dry-run] [--plan]
-  linkany uninstall [-m <manifest>] [--dry-run] [--plan]
+  linkany add --source <path> --target <path> [--kind file|dir] [--atomic|--no-atomic] [-m <manifest>] [--dry-run] [--plan] [--no-audit]
+  linkany remove <key> [--keep-link] [-m <manifest>] [--dry-run] [--plan] [--no-audit]
+  linkany install [-m <manifest>] [--dry-run] [--plan] [--no-audit]
+  linkany uninstall [-m <manifest>] [--dry-run] [--plan] [--no-audit]
 `;
     process.stdout.write(msg.trimStart());
     process.stdout.write('\n');
@@ -123,9 +124,9 @@ export async function main(argv = process.argv.slice(2)) {
             const mapping = parseAddArgs(args);
             if (args.length)
                 die(`Unknown arguments: ${args.join(' ')}`);
-            const res = await add(manifestPath, mapping, opts);
-            process.stdout.write(JSON.stringify(res, null, 2) + '\n');
-            return res.ok ? 0 : 1;
+            const { result } = await add(manifestPath, mapping, opts);
+            process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+            return result.ok ? 0 : 1;
         }
         if (cmd === 'remove') {
             const opts = parseCommonOptions(args);
@@ -136,27 +137,27 @@ export async function main(argv = process.argv.slice(2)) {
                 die('remove requires <key>');
             if (args.length)
                 die(`Unknown arguments: ${args.join(' ')}`);
-            const res = await remove(manifestPath, key, { ...opts, keepLink });
-            process.stdout.write(JSON.stringify(res, null, 2) + '\n');
-            return res.ok ? 0 : 1;
+            const { result } = await remove(manifestPath, key, { ...opts, keepLink });
+            process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+            return result.ok ? 0 : 1;
         }
         if (cmd === 'install') {
             const opts = parseCommonOptions(args);
             const manifestPath = await resolveManifestPath(args);
             if (args.length)
                 die(`Unknown arguments: ${args.join(' ')}`);
-            const res = await install(manifestPath, opts);
-            process.stdout.write(JSON.stringify(res, null, 2) + '\n');
-            return res.ok ? 0 : 1;
+            const { result } = await install(manifestPath, opts);
+            process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+            return result.ok ? 0 : 1;
         }
         if (cmd === 'uninstall') {
             const opts = parseCommonOptions(args);
             const manifestPath = await resolveManifestPath(args);
             if (args.length)
                 die(`Unknown arguments: ${args.join(' ')}`);
-            const res = await uninstall(manifestPath, opts);
-            process.stdout.write(JSON.stringify(res, null, 2) + '\n');
-            return res.ok ? 0 : 1;
+            const { result } = await uninstall(manifestPath, opts);
+            process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+            return result.ok ? 0 : 1;
         }
         die(`Unknown command: ${cmd}`);
     }

package/dist/core/audit.d.ts

@@ -1,4 +1,4 @@
 import { CommonOptions, Result } from '../types.js';
 export declare function defaultAuditLogPath(manifestPath: string, opts?: CommonOptions): string;
 export declare function appendAudit(logPath: string, result: Result): Promise<void>;
-export declare function tryAppendAuditStep(result: Result, manifestPath: string, opts?: CommonOptions): Promise<Result>;
+export declare function tryAppendAuditStep(result: Result, manifestPath?: string, opts?: CommonOptions): Promise<Result>;

package/dist/core/audit.js

@@ -9,7 +9,11 @@ export async function appendAudit(logPath, result) {
     await fs.appendFile(logPath, line, 'utf8');
 }
 export async function tryAppendAuditStep(result, manifestPath, opts) {
-    const logPath = defaultAuditLogPath(manifestPath, opts);
+    if (opts?.audit === false)
+        return result;
+    const logPath = opts?.auditLogPath ?? (manifestPath ? `${path.resolve(manifestPath)}.log.jsonl` : undefined);
+    if (!logPath)
+        return result;
     try {
         await appendAudit(logPath, result);
         result.steps.push({ kind: 'audit', message: 'Append audit log', status: 'executed', paths: { file: logPath } });

package/dist/core/runner.d.ts

@@ -1,7 +1,7 @@
 import { CommonOptions, Result, Step } from '../types.js';
 export interface RunOperationInput {
     operation: Result['operation'];
-    manifestPath: string;
+    manifestPath?: string;
     steps: Step[];
     opts?: CommonOptions;
     /**

package/dist/core/runner.js

@@ -13,7 +13,8 @@ export async function runOperation(input) {
         dryRun: input.opts?.dryRun,
     });
     res.operation = input.operation;
-    res.manifestPath = input.manifestPath;
+    if (input.manifestPath)
+        res.manifestPath = input.manifestPath;
     res.startedAt = startedAt;
     res.durationMs = Date.now() - startedMs;
     res.finishedAt = nowIso();
@@ -23,7 +24,9 @@ export async function runOperation(input) {
     if (input.finalize) {
         res = await input.finalize(res);
     }
-    res = await tryAppendAuditStep(res, input.manifestPath, input.opts);
+    if (input.opts?.audit !== false) {
+        res = await tryAppendAuditStep(res, input.manifestPath, input.opts);
+    }
     logger?.info?.(`[linkany] ${input.operation} ${res.ok ? 'ok' : 'fail'} (${res.durationMs}ms)`);
     return res;
 }

package/dist/types.d.ts

@@ -55,6 +55,13 @@ export interface Logger {
     error(msg: string): void;
 }
 export interface CommonOptions {
+    /**
+     * Whether to append an audit log entry for this operation.
+     * Default: true.
+     *
+     * Set to false if the caller wants to fully disable audit logging and handle it themselves.
+     */
+    audit?: boolean;
     /**
      * If provided, we append one JSON line per operation (Result summary).
      * Default strategy (V1): `${manifestPath}.log.jsonl` when manifestPath is known.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linkany",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",