linkany 0.0.1

package/dist/cli.js

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { add } from './api/add.js';
+import { install } from './api/install.js';
+import { remove } from './api/remove.js';
+import { uninstall } from './api/uninstall.js';
+import { clearDefaultManifestPath, getDefaultManifestPath, setDefaultManifestPath } from './cli/config.js';
+class CliExit extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.exitCode = exitCode;
+    }
+}
+function die(msg, code = 1) {
+    throw new CliExit(msg, code);
+}
+function popFlagValue(args, names) {
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (!names.includes(a))
+            continue;
+        const v = args[i + 1];
+        if (!v || v.startsWith('-'))
+            return undefined;
+        args.splice(i, 2);
+        return v;
+    }
+    return undefined;
+}
+function hasFlag(args, names) {
+    const idx = args.findIndex(a => names.includes(a));
+    if (idx >= 0) {
+        args.splice(idx, 1);
+        return true;
+    }
+    return false;
+}
+function parseCommonOptions(args) {
+    const dryRun = hasFlag(args, ['--dry-run']);
+    const includePlanText = hasFlag(args, ['--plan']);
+    const auditLogPath = popFlagValue(args, ['--audit-log']);
+    return { dryRun, includePlanText, auditLogPath };
+}
+async function resolveManifestPath(args) {
+    const m = popFlagValue(args, ['-m', '--manifest']);
+    if (m)
+        return path.resolve(m);
+    const d = await getDefaultManifestPath();
+    if (d)
+        return d;
+    die('No manifest specified. Please run `linkany manifest set <path>` or pass `--manifest <path>`.');
+}
+function printHelp() {
+    const msg = `
+linkany
+
+Usage:
+  linkany manifest set <path>
+  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]
+`;
+    process.stdout.write(msg.trimStart());
+    process.stdout.write('\n');
+}
+function parseAddArgs(args) {
+    const source = popFlagValue(args, ['--source']);
+    const target = popFlagValue(args, ['--target']);
+    const kind = popFlagValue(args, ['--kind']);
+    const atomic = hasFlag(args, ['--atomic']) ? true : (hasFlag(args, ['--no-atomic']) ? false : undefined);
+    if (!source || !target) {
+        die('add requires --source and --target');
+    }
+    if (kind && kind !== 'file' && kind !== 'dir') {
+        die(`Invalid --kind: ${kind} (expected file|dir)`);
+    }
+    return { source, target, kind, atomic };
+}
+export async function main(argv = process.argv.slice(2)) {
+    try {
+        const args = [...argv];
+        if (args.length === 0 || hasFlag(args, ['-h', '--help'])) {
+            printHelp();
+            return 0;
+        }
+        const cmd = args.shift();
+        if (!cmd) {
+            printHelp();
+            return 1;
+        }
+        if (cmd === 'manifest') {
+            const sub = args.shift();
+            if (sub === 'set') {
+                const p = args.shift();
+                if (!p)
+                    die('manifest set requires a path');
+                const abs = await setDefaultManifestPath(p);
+                process.stdout.write(abs + '\n');
+                return 0;
+            }
+            if (sub === 'show') {
+                const p = await getDefaultManifestPath();
+                if (!p)
+                    die('No default manifest set. Run `linkany manifest set <path>`.', 2);
+                process.stdout.write(p + '\n');
+                return 0;
+            }
+            if (sub === 'clear') {
+                await clearDefaultManifestPath();
+                return 0;
+            }
+            die('Unknown manifest subcommand. Expected: set|show|clear');
+        }
+        if (cmd === 'add') {
+            const opts = parseCommonOptions(args);
+            const manifestPath = await resolveManifestPath(args);
+            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;
+        }
+        if (cmd === 'remove') {
+            const opts = parseCommonOptions(args);
+            const manifestPath = await resolveManifestPath(args);
+            const keepLink = hasFlag(args, ['--keep-link']);
+            const key = args.shift();
+            if (!key)
+                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;
+        }
+        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;
+        }
+        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;
+        }
+        die(`Unknown command: ${cmd}`);
+    }
+    catch (e) {
+        if (e instanceof CliExit) {
+            const msg = e.message || 'Command failed';
+            process.stderr.write(msg.endsWith('\n') ? msg : msg + '\n');
+            return e.exitCode;
+        }
+        throw e;
+    }
+}
+// Only run when executed as a script, not when imported (e.g., tests).
+const isEntry = process.argv[1] &&
+    path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));
+if (isEntry) {
+    main().then((code) => process.exit(code), (err) => {
+        const msg = err?.stack ? String(err.stack) : String(err);
+        process.stderr.write(msg.endsWith('\n') ? msg : msg + '\n');
+        process.exit(1);
+    });
+}

package/dist/core/apply.d.ts

@@ -0,0 +1,6 @@
+import { Logger, Result, Step } from '../types.js';
+export interface ApplyOptions {
+    logger?: Logger;
+    dryRun?: boolean;
+}
+export declare function applyPlan(operation: Result['operation'], steps: Step[], opts?: ApplyOptions): Promise<Result>;

package/dist/core/apply.js

@@ -0,0 +1,159 @@
+import path from 'path';
+import fs from 'fs-extra';
+import { copyPath, createDir, createEmptyFile, createSymlink, removePath, removeSymlink, renameAtomic } from './fs-ops.js';
+function nowIso() {
+    return new Date().toISOString();
+}
+function durationMs(start) {
+    return Date.now() - start;
+}
+function defaultLogger() {
+    return {
+        info: () => { },
+        warn: () => { },
+        error: () => { },
+    };
+}
+export async function applyPlan(operation, steps, opts = {}) {
+    const startTs = Date.now();
+    const startedAt = nowIso();
+    const logger = opts.logger ?? defaultLogger();
+    const result = {
+        ok: true,
+        operation,
+        startedAt,
+        finishedAt: startedAt,
+        durationMs: 0,
+        steps: [],
+        warnings: [],
+        errors: [],
+        changes: [],
+    };
+    for (const s of steps) {
+        const step = { ...s, status: 'planned' };
+        try {
+            if (opts.dryRun && s.kind !== 'noop') {
+                step.status = 'skipped';
+                result.steps.push(step);
+                continue;
+            }
+            switch (s.kind) {
+                case 'noop':
+                    step.status = 'skipped';
+                    break;
+                case 'mkdirp': {
+                    const dir = s.paths?.dir;
+                    if (!dir)
+                        throw new Error('mkdirp step missing dir');
+                    await createDir(dir);
+                    step.status = 'executed';
+                    break;
+                }
+                case 'touch': {
+                    const file = s.paths?.file;
+                    if (!file)
+                        throw new Error('touch step missing file');
+                    await createEmptyFile(file);
+                    step.status = 'executed';
+                    result.changes.push({ action: 'create_source_file', source: file });
+                    break;
+                }
+                case 'symlink': {
+                    const source = s.paths?.source;
+                    const target = s.paths?.target;
+                    if (!source || !target)
+                        throw new Error('symlink step missing source/target');
+                    let kind = s.paths?.kind;
+                    if (!kind) {
+                        try {
+                            const st = await fs.lstat(source);
+                            kind = st.isDirectory() ? 'dir' : 'file';
+                        }
+                        catch {
+                            kind = 'file';
+                        }
+                    }
+                    await createSymlink(source, target, kind);
+                    step.status = 'executed';
+                    result.changes.push({ action: 'symlink', source, target });
+                    step.undo = { kind: 'unlink', message: 'Rollback: remove created symlink', paths: { target } };
+                    break;
+                }
+                case 'unlink': {
+                    const target = s.paths?.target;
+                    if (!target)
+                        throw new Error('unlink step missing target');
+                    await removeSymlink(target);
+                    step.status = 'executed';
+                    result.changes.push({ action: 'unlink', target });
+                    break;
+                }
+                case 'rm': {
+                    const p = s.paths?.path;
+                    if (!p)
+                        throw new Error('rm step missing path');
+                    await removePath(p);
+                    step.status = 'executed';
+                    result.changes.push({ action: 'rm', target: p });
+                    break;
+                }
+                case 'move': {
+                    const from = s.paths?.from;
+                    const to = s.paths?.to;
+                    if (!from || !to)
+                        throw new Error('move step missing from/to');
+                    await renameAtomic(from, to);
+                    step.status = 'executed';
+                    result.changes.push({ action: 'move', source: from, target: to });
+                    step.undo = step.undo ?? { kind: 'move', message: 'Rollback: move back', paths: { from: to, to: from } };
+                    break;
+                }
+                case 'copy': {
+                    const from = s.paths?.from;
+                    const to = s.paths?.to;
+                    if (!from || !to)
+                        throw new Error('copy step missing from/to');
+                    await copyPath(from, to);
+                    step.status = 'executed';
+                    result.changes.push({ action: 'copy', source: from, target: to });
+                    break;
+                }
+                case 'write_manifest':
+                case 'audit':
+                    step.status = 'skipped';
+                    break;
+                default: {
+                    const _exhaustive = s.kind;
+                    throw new Error(`Unknown step kind: ${String(_exhaustive)}`);
+                }
+            }
+            result.steps.push(step);
+        }
+        catch (e) {
+            step.status = 'failed';
+            step.error = e?.message ? String(e.message) : String(e);
+            result.steps.push(step);
+            result.ok = false;
+            result.errors.push(step.error);
+            logger.error(`[linkany] step failed: ${step.kind} ${step.error}`);
+            const tmp = step.paths?.target && path.basename(step.paths.target).includes('.tmp.')
+                ? step.paths.target
+                : undefined;
+            if (tmp) {
+                try {
+                    await removePath(tmp);
+                }
+                catch { }
+            }
+            break;
+        }
+    }
+    // Build a best-effort rollback plan in reverse execution order.
+    result.rollbackSteps = result.steps
+        .filter(s => s.status === 'executed' && s.undo)
+        .map(s => s.undo)
+        .reverse();
+    result.finishedAt = nowIso();
+    result.durationMs = durationMs(startTs);
+    return result;
+}

package/dist/core/audit.d.ts

@@ -0,0 +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>;

package/dist/core/audit.js

@@ -0,0 +1,23 @@
+import fs from 'fs-extra';
+import path from 'path';
+export function defaultAuditLogPath(manifestPath, opts) {
+    return opts?.auditLogPath ?? `${path.resolve(manifestPath)}.log.jsonl`;
+}
+export async function appendAudit(logPath, result) {
+    await fs.ensureDir(path.dirname(logPath));
+    const line = JSON.stringify(result) + '\n';
+    await fs.appendFile(logPath, line, 'utf8');
+}
+export async function tryAppendAuditStep(result, manifestPath, opts) {
+    const logPath = defaultAuditLogPath(manifestPath, opts);
+    try {
+        await appendAudit(logPath, result);
+        result.steps.push({ kind: 'audit', message: 'Append audit log', status: 'executed', paths: { file: logPath } });
+    }
+    catch (e) {
+        const msg = e?.message ? String(e.message) : String(e);
+        result.warnings.push(`Failed to write audit log: ${msg}`);
+        result.steps.push({ kind: 'audit', message: 'Append audit log', status: 'failed', error: msg, paths: { file: logPath } });
+    }
+    return result;
+}

package/dist/core/backup.d.ts

@@ -0,0 +1,18 @@
+import { Step } from '../types.js';
+export declare function backupPathForTarget(targetAbs: string): string;
+/**
+ * Plan an atomic replace for symlink target:
+ * - create tmp symlink (done elsewhere)
+ * - move existing target to backup
+ * - move tmp into place
+ *
+ * This does NOT delete backups; leaving backups is safer and aids rollback.
+ */
+export declare function planReplaceTargetWithTmp(opts: {
+    targetAbs: string;
+    atomic: boolean;
+}): {
+    backupAbs?: string;
+    steps: Step[];
+    tmpAbs: string;
+};

package/dist/core/backup.js

@@ -0,0 +1,44 @@
+import { tmpPathForTarget } from './plan.js';
+function rand() {
+    return Math.random().toString(16).slice(2);
+}
+export function backupPathForTarget(targetAbs) {
+    return `${targetAbs}.bak.${Date.now()}.${rand()}`;
+}
+/**
+ * Plan an atomic replace for symlink target:
+ * - create tmp symlink (done elsewhere)
+ * - move existing target to backup
+ * - move tmp into place
+ *
+ * This does NOT delete backups; leaving backups is safer and aids rollback.
+ */
+export function planReplaceTargetWithTmp(opts) {
+    const steps = [];
+    const tmpAbs = opts.atomic ? tmpPathForTarget(opts.targetAbs) : opts.targetAbs;
+    if (opts.atomic) {
+        const backupAbs = backupPathForTarget(opts.targetAbs);
+        steps.push({
+            kind: 'move',
+            message: 'Move existing target aside to backup before replacement',
+            paths: { from: opts.targetAbs, to: backupAbs },
+            undo: {
+                kind: 'move',
+                message: 'Rollback: restore previous target from backup',
+                paths: { from: backupAbs, to: opts.targetAbs },
+            },
+        });
+        steps.push({
+            kind: 'move',
+            message: 'Atomically move temp symlink into place',
+            paths: { from: tmpAbs, to: opts.targetAbs },
+            undo: {
+                kind: 'move',
+                message: 'Rollback: move current target back to tmp',
+                paths: { from: opts.targetAbs, to: tmpAbs },
+            },
+        });
+        return { backupAbs, steps, tmpAbs };
+    }
+    return { steps, tmpAbs };
+}

package/dist/core/format-plan.d.ts

@@ -0,0 +1,2 @@
+import { Step } from '../types.js';
+export declare function formatPlan(steps: Step[]): string;

package/dist/core/format-plan.js

@@ -0,0 +1,14 @@
+export function formatPlan(steps) {
+    if (!steps.length)
+        return 'No changes.';
+    const lines = [];
+    for (const s of steps) {
+        const paths = s.paths
+            ? Object.entries(s.paths)
+                .map(([k, v]) => `${k}=${v}`)
+                .join(' ')
+            : '';
+        lines.push(`- ${s.kind}: ${s.message}${paths ? ` (${paths})` : ''}`);
+    }
+    return lines.join('\n');
+}

package/dist/core/fs-ops.d.ts

@@ -0,0 +1,16 @@
+import { LinkKind } from '../types.js';
+export declare function ensureParentDir(p: string): Promise<void>;
+export declare function createEmptyFile(p: string): Promise<void>;
+export declare function createDir(p: string): Promise<void>;
+/**
+ * Create a symlink at target pointing to source.
+ * On macOS/Linux we do not fallback to copy. If symlink fails, it throws.
+ */
+export declare function createSymlink(sourceAbs: string, targetAbs: string, kind: LinkKind): Promise<void>;
+export declare function removePath(p: string): Promise<void>;
+/**
+ * Remove only if it's a symlink. Throws if it exists but isn't a symlink.
+ */
+export declare function removeSymlink(p: string): Promise<void>;
+export declare function renameAtomic(from: string, to: string): Promise<void>;
+export declare function copyPath(from: string, to: string): Promise<void>;

package/dist/core/fs-ops.js

@@ -0,0 +1,41 @@
+import fs from 'fs-extra';
+import path from 'path';
+export async function ensureParentDir(p) {
+    await fs.ensureDir(path.dirname(p));
+}
+export async function createEmptyFile(p) {
+    await ensureParentDir(p);
+    await fs.ensureFile(p);
+}
+export async function createDir(p) {
+    await fs.ensureDir(p);
+}
+/**
+ * Create a symlink at target pointing to source.
+ * On macOS/Linux we do not fallback to copy. If symlink fails, it throws.
+ */
+export async function createSymlink(sourceAbs, targetAbs, kind) {
+    await ensureParentDir(targetAbs);
+    const rel = path.relative(path.dirname(targetAbs), sourceAbs) || '.';
+    await fs.symlink(rel, targetAbs, kind === 'dir' ? 'dir' : 'file');
+}
+export async function removePath(p) {
+    await fs.remove(p);
+}
+/**
+ * Remove only if it's a symlink. Throws if it exists but isn't a symlink.
+ */
+export async function removeSymlink(p) {
+    const st = await fs.lstat(p);
+    if (!st.isSymbolicLink()) {
+        throw new Error(`Refusing to remove non-symlink: ${p}`);
+    }
+    await fs.unlink(p);
+}
+export async function renameAtomic(from, to) {
+    await fs.rename(from, to);
+}
+export async function copyPath(from, to) {
+    await ensureParentDir(to);
+    await fs.copy(from, to, { dereference: true });
+}

package/dist/core/fs.d.ts

@@ -0,0 +1,7 @@
+import fs from 'fs-extra';
+export interface FS {
+    pathExists(p: string): Promise<boolean>;
+    lstat(p: string): Promise<fs.Stats>;
+    readlink(p: string): Promise<string>;
+}
+export declare const nodeFS: FS;

package/dist/core/fs.js

@@ -0,0 +1,6 @@
+import fs from 'fs-extra';
+export const nodeFS = {
+    pathExists: fs.pathExists,
+    lstat: fs.lstat,
+    readlink: fs.readlink,
+};

package/dist/core/plan.d.ts

@@ -0,0 +1,40 @@
+import { LinkKind, Step } from '../types.js';
+import { FS } from './fs.js';
+export interface EnsureSourceSpec {
+    sourceAbs: string;
+    kind: LinkKind;
+}
+export interface EnsureLinkSpec {
+    sourceAbs: string;
+    targetAbs: string;
+    kind: LinkKind;
+    atomic: boolean;
+}
+export interface UnlinkSpec {
+    targetAbs: string;
+}
+export interface CopySpec {
+    fromAbs: string;
+    toAbs: string;
+    kind: LinkKind;
+    atomic: boolean;
+}
+export declare function tmpPathForTarget(targetAbs: string): string;
+export declare function backupPathForTarget(targetAbs: string): string;
+export declare function detectKind(p: string): Promise<LinkKind>;
+export declare function detectKindWithFS(fs: FS, p: string): Promise<LinkKind>;
+export declare function isSymlinkTo(targetAbs: string, sourceAbs: string): Promise<boolean>;
+export declare function isSymlinkToWithFS(fs: FS, targetAbs: string, sourceAbs: string): Promise<boolean>;
+export declare function planEnsureSource(spec: EnsureSourceSpec): Promise<Step[]>;
+export declare function planEnsureSourceWithFS(fs: FS, spec: EnsureSourceSpec): Promise<Step[]>;
+export declare function planEnsureLink(spec: EnsureLinkSpec): Promise<{
+    steps: Step[];
+    reason: 'noop' | 'create' | 'replace_symlink' | 'conflict';
+}>;
+export declare function planEnsureLinkWithFS(fs: FS, spec: EnsureLinkSpec): Promise<{
+    steps: Step[];
+    reason: 'noop' | 'create' | 'replace_symlink' | 'conflict';
+}>;
+export declare function planUnlink(spec: UnlinkSpec): Promise<Step[]>;
+export declare function planUnlinkWithFS(fs: FS, spec: UnlinkSpec): Promise<Step[]>;
+export declare function planCopy(spec: CopySpec): Promise<Step[]>;