linkany 0.0.1

package/dist/core/plan.js

@@ -0,0 +1,149 @@
+import path from 'path';
+import { nodeFS } from './fs.js';
+function rand() {
+    return Math.random().toString(16).slice(2);
+}
+export function tmpPathForTarget(targetAbs) {
+    return `${targetAbs}.tmp.${rand()}`;
+}
+export function backupPathForTarget(targetAbs) {
+    return `${targetAbs}.bak.${Date.now()}.${rand()}`;
+}
+export async function detectKind(p) {
+    return detectKindWithFS(nodeFS, p);
+}
+export async function detectKindWithFS(fs, p) {
+    const st = await fs.lstat(p);
+    if (st.isDirectory())
+        return 'dir';
+    return 'file';
+}
+export async function isSymlinkTo(targetAbs, sourceAbs) {
+    return isSymlinkToWithFS(nodeFS, targetAbs, sourceAbs);
+}
+export async function isSymlinkToWithFS(fs, targetAbs, sourceAbs) {
+    try {
+        const st = await fs.lstat(targetAbs);
+        if (!st.isSymbolicLink())
+            return false;
+        const link = await fs.readlink(targetAbs);
+        const resolved = path.resolve(path.dirname(targetAbs), link);
+        return path.normalize(resolved) === path.normalize(sourceAbs);
+    }
+    catch {
+        return false;
+    }
+}
+export async function planEnsureSource(spec) {
+    return planEnsureSourceWithFS(nodeFS, spec);
+}
+export async function planEnsureSourceWithFS(fs, spec) {
+    const steps = [];
+    if (await fs.pathExists(spec.sourceAbs))
+        return steps;
+    steps.push({
+        kind: 'mkdirp',
+        message: `Ensure parent dir for source exists`,
+        paths: { dir: path.dirname(spec.sourceAbs) },
+    });
+    if (spec.kind === 'dir') {
+        steps.push({
+            kind: 'mkdirp',
+            message: `Create source directory`,
+            paths: { dir: spec.sourceAbs },
+        });
+    }
+    else {
+        steps.push({
+            kind: 'touch',
+            message: `Create empty source file`,
+            paths: { file: spec.sourceAbs },
+        });
+    }
+    return steps;
+}
+export async function planEnsureLink(spec) {
+    return planEnsureLinkWithFS(nodeFS, spec);
+}
+export async function planEnsureLinkWithFS(fs, spec) {
+    const steps = [];
+    if (await isSymlinkToWithFS(fs, spec.targetAbs, spec.sourceAbs)) {
+        return { steps, reason: 'noop' };
+    }
+    const targetExists = await fs.pathExists(spec.targetAbs);
+    if (targetExists) {
+        const st = await fs.lstat(spec.targetAbs);
+        if (!st.isSymbolicLink()) {
+            return { steps, reason: 'conflict' };
+        }
+        steps.push({
+            kind: 'unlink',
+            message: 'Remove existing symlink before re-link',
+            paths: { target: spec.targetAbs },
+        });
+    }
+    steps.push({
+        kind: 'mkdirp',
+        message: 'Ensure target parent directory exists',
+        paths: { dir: path.dirname(spec.targetAbs) },
+    });
+    const tmp = spec.atomic ? tmpPathForTarget(spec.targetAbs) : spec.targetAbs;
+    steps.push({
+        kind: 'symlink',
+        message: spec.atomic ? 'Create symlink at temp path' : 'Create symlink',
+        paths: { source: spec.sourceAbs, target: tmp, kind: spec.kind },
+    });
+    if (spec.atomic) {
+        steps.push({
+            kind: 'move',
+            message: 'Atomically move temp symlink into place',
+            paths: { from: tmp, to: spec.targetAbs },
+        });
+    }
+    return { steps, reason: targetExists ? 'replace_symlink' : 'create' };
+}
+export async function planUnlink(spec) {
+    return planUnlinkWithFS(nodeFS, spec);
+}
+export async function planUnlinkWithFS(fs, spec) {
+    const steps = [];
+    if (!await fs.pathExists(spec.targetAbs))
+        return steps;
+    const st = await fs.lstat(spec.targetAbs);
+    if (!st.isSymbolicLink()) {
+        steps.push({
+            kind: 'noop',
+            message: 'Target exists but is not a symlink; skipping unlink for safety',
+            paths: { target: spec.targetAbs },
+        });
+        return steps;
+    }
+    steps.push({
+        kind: 'unlink',
+        message: 'Remove target symlink',
+        paths: { target: spec.targetAbs },
+    });
+    return steps;
+}
+export async function planCopy(spec) {
+    const steps = [];
+    steps.push({
+        kind: 'mkdirp',
+        message: 'Ensure destination parent directory exists',
+        paths: { dir: path.dirname(spec.toAbs) },
+    });
+    const tmp = spec.atomic ? tmpPathForTarget(spec.toAbs) : spec.toAbs;
+    steps.push({
+        kind: 'copy',
+        message: spec.atomic ? 'Copy to temp destination' : 'Copy to destination',
+        paths: { from: spec.fromAbs, to: tmp, kind: spec.kind },
+    });
+    if (spec.atomic) {
+        steps.push({
+            kind: 'move',
+            message: 'Atomically move copied temp into place',
+            paths: { from: tmp, to: spec.toAbs },
+        });
+    }
+    return steps;
+}

package/dist/core/runner.d.ts

@@ -0,0 +1,13 @@
+import { CommonOptions, Result, Step } from '../types.js';
+export interface RunOperationInput {
+    operation: Result['operation'];
+    manifestPath: string;
+    steps: Step[];
+    opts?: CommonOptions;
+    /**
+     * Called after apply (or dry-run) but before audit is appended.
+     * Allows callers to push extra steps (e.g., write_manifest) and mark failure.
+     */
+    finalize?: (result: Result) => Promise<Result> | Result;
+}
+export declare function runOperation(input: RunOperationInput): Promise<Result>;

package/dist/core/runner.js

@@ -0,0 +1,29 @@
+import { applyPlan } from './apply.js';
+import { tryAppendAuditStep } from './audit.js';
+import { formatPlan } from './format-plan.js';
+function nowIso() {
+    return new Date().toISOString();
+}
+export async function runOperation(input) {
+    const startedAt = nowIso();
+    const startedMs = Date.now();
+    const logger = input.opts?.logger;
+    let res = await applyPlan(input.operation, input.steps, {
+        logger,
+        dryRun: input.opts?.dryRun,
+    });
+    res.operation = input.operation;
+    res.manifestPath = input.manifestPath;
+    res.startedAt = startedAt;
+    res.durationMs = Date.now() - startedMs;
+    res.finishedAt = nowIso();
+    if (input.opts?.includePlanText) {
+        res.planText = formatPlan(input.steps);
+    }
+    if (input.finalize) {
+        res = await input.finalize(res);
+    }
+    res = await tryAppendAuditStep(res, input.manifestPath, input.opts);
+    logger?.info?.(`[linkany] ${input.operation} ${res.ok ? 'ok' : 'fail'} (${res.durationMs}ms)`);
+    return res;
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export type { Manifest, InstallEntry, InstallKind } from './manifest/types.js';
+export type { Mapping } from './api/add.js';
+export type { RemoveOptions } from './api/remove.js';
+export type { Result, Step, Logger, CommonOptions, LinkKind } from './types.js';
+export { loadManifest } from './manifest/types.js';
+export { loadOrCreateManifest, saveManifest, upsertEntry, removeEntry } from './manifest/io.js';
+export { add, remove, install, uninstall } from './api/index.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { loadManifest } from './manifest/types.js';
+export { loadOrCreateManifest, saveManifest, upsertEntry, removeEntry } from './manifest/io.js';
+export { add, remove, install, uninstall } from './api/index.js';

package/dist/manifest/io.d.ts

@@ -0,0 +1,17 @@
+import { InstallEntry, Manifest } from './types.js';
+export declare function loadOrCreateManifest(manifestPath: string): Promise<Manifest>;
+export interface SaveManifestOptions {
+    spaces?: number;
+}
+export declare function saveManifest(manifestPath: string, manifest: Manifest, opts?: SaveManifestOptions): Promise<void>;
+export interface UpsertEntryResult {
+    updated: boolean;
+    created: boolean;
+    key: string;
+}
+export declare function upsertEntry(manifest: Manifest, entry: InstallEntry): UpsertEntryResult;
+export interface RemoveEntryResult {
+    removed: boolean;
+    key: string;
+}
+export declare function removeEntry(manifest: Manifest, key: string): RemoveEntryResult;

package/dist/manifest/io.js

@@ -0,0 +1,52 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { normalizeManifest } from './types.js';
+function defaultManifest() {
+    return {
+        version: 1,
+        installs: [],
+    };
+}
+export async function loadOrCreateManifest(manifestPath) {
+    const abs = path.resolve(manifestPath);
+    if (!await fs.pathExists(abs)) {
+        return defaultManifest();
+    }
+    const json = await fs.readJson(abs);
+    return normalizeManifest(json);
+}
+export async function saveManifest(manifestPath, manifest, opts = {}) {
+    const abs = path.resolve(manifestPath);
+    await fs.ensureDir(path.dirname(abs));
+    const spaces = opts.spaces ?? 2;
+    const content = JSON.stringify(manifest, null, spaces) + '\n';
+    const tmp = `${abs}.tmp.${Date.now()}.${Math.random().toString(16).slice(2)}`;
+    await fs.writeFile(tmp, content, 'utf8');
+    await fs.rename(tmp, abs);
+}
+function keyOf(entry) {
+    return entry.id || entry.target;
+}
+export function upsertEntry(manifest, entry) {
+    const key = keyOf(entry);
+    if (!key)
+        throw new Error('Entry must have "target" (or "id")');
+    const installs = manifest.installs ?? (manifest.installs = []);
+    const idx = installs.findIndex(e => keyOf(e) === key);
+    if (idx >= 0) {
+        installs[idx] = { ...installs[idx], ...entry };
+        return { updated: true, created: false, key };
+    }
+    installs.push(entry);
+    return { updated: false, created: true, key };
+}
+export function removeEntry(manifest, key) {
+    if (!key)
+        throw new Error('removeEntry requires a key');
+    const installs = manifest.installs ?? (manifest.installs = []);
+    const idx = installs.findIndex(e => keyOf(e) === key || e.target === key);
+    if (idx < 0)
+        return { removed: false, key };
+    installs.splice(idx, 1);
+    return { removed: true, key };
+}

package/dist/manifest/types.d.ts

@@ -0,0 +1,29 @@
+export type ManifestVersion = 1;
+export type InstallKind = 'file' | 'dir';
+export interface InstallEntry {
+    id?: string;
+    source: string;
+    target: string;
+    kind?: InstallKind;
+    atomic?: boolean;
+}
+/**
+ * Users can add any extra fields.
+ */
+export interface Manifest {
+    version: ManifestVersion;
+    installs: InstallEntry[];
+    [k: string]: any;
+}
+export interface ResolvedInstallEntry extends InstallEntry {
+    sourceAbs: string;
+    targetAbs: string;
+    manifestKey: string;
+    atomic: boolean;
+}
+export declare function getManifestBaseDir(manifestPath: string): string;
+export declare function resolveMaybeRelative(baseDir: string, p: string): string;
+export declare function getEntryKey(entry: InstallEntry): string;
+export declare function resolveEntry(baseDir: string, entry: InstallEntry): ResolvedInstallEntry;
+export declare function normalizeManifest(raw: unknown): Manifest;
+export declare function loadManifest(manifestPath: string): Promise<Manifest>;

package/dist/manifest/types.js

@@ -0,0 +1,44 @@
+import path from 'path';
+import fs from 'fs-extra';
+export function getManifestBaseDir(manifestPath) {
+    return path.dirname(path.resolve(manifestPath));
+}
+export function resolveMaybeRelative(baseDir, p) {
+    if (!p)
+        return p;
+    return path.isAbsolute(p) ? path.normalize(p) : path.normalize(path.resolve(baseDir, p));
+}
+export function getEntryKey(entry) {
+    return entry.id || entry.target;
+}
+export function resolveEntry(baseDir, entry) {
+    const sourceAbs = resolveMaybeRelative(baseDir, entry.source);
+    const targetAbs = resolveMaybeRelative(baseDir, entry.target);
+    return {
+        ...entry,
+        sourceAbs,
+        targetAbs,
+        manifestKey: getEntryKey(entry),
+        atomic: entry.atomic ?? true,
+    };
+}
+export function normalizeManifest(raw) {
+    const obj = (raw ?? {});
+    const version = obj.version;
+    const installs = obj.installs;
+    if (version !== 1) {
+        throw new Error(`Unsupported manifest version: ${String(version)} (expected 1)`);
+    }
+    if (!Array.isArray(installs)) {
+        throw new Error('Invalid manifest: "installs" must be an array');
+    }
+    return { ...obj, version: 1, installs: installs };
+}
+export async function loadManifest(manifestPath) {
+    const abs = path.resolve(manifestPath);
+    if (!await fs.pathExists(abs)) {
+        throw new Error(`Manifest not found: ${abs}`);
+    }
+    const json = await fs.readJson(abs);
+    return normalizeManifest(json);
+}

package/dist/types.d.ts

@@ -0,0 +1,72 @@
+export type LinkKind = 'file' | 'dir';
+export type Operation = 'install' | 'uninstall' | 'add' | 'remove';
+export type StepKind = 'noop' | 'mkdirp' | 'touch' | 'symlink' | 'unlink' | 'rm' | 'move' | 'copy' | 'write_manifest' | 'audit';
+export interface Step {
+    kind: StepKind;
+    message: string;
+    /**
+     * Optional paths involved in the step, for observability and auditing.
+     */
+    paths?: Record<string, string>;
+    /**
+     * Whether the step was executed or skipped.
+     */
+    status?: 'planned' | 'executed' | 'skipped' | 'failed';
+    /**
+     * Optional error message for failed steps.
+     */
+    error?: string;
+    /**
+     * Optional rollback hint for this step (protocol only; may be partial).
+     * If present and the step was executed, a future rollback can apply this.
+     */
+    undo?: Omit<Step, 'status' | 'error' | 'undo'>;
+}
+export interface Result {
+    ok: boolean;
+    operation: Operation;
+    manifestPath?: string;
+    startedAt: string;
+    finishedAt: string;
+    durationMs: number;
+    steps: Step[];
+    warnings: string[];
+    errors: string[];
+    /**
+     * Summary of changes that occurred.
+     */
+    changes: Array<{
+        target?: string;
+        source?: string;
+        action: string;
+    }>;
+    /**
+     * Optional rollback plan (best-effort) in reverse order of execution.
+     */
+    rollbackSteps?: Step[];
+    /**
+     * Optional human-readable plan / summary text (best-effort).
+     */
+    planText?: string;
+}
+export interface Logger {
+    info(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+}
+export interface CommonOptions {
+    /**
+     * If provided, we append one JSON line per operation (Result summary).
+     * Default strategy (V1): `${manifestPath}.log.jsonl` when manifestPath is known.
+     */
+    auditLogPath?: string;
+    logger?: Logger;
+    /**
+     * If true, do not perform filesystem writes; only return the planned steps/result.
+     */
+    dryRun?: boolean;
+    /**
+     * If true, return plan text in Result.planText (best-effort).
+     */
+    includePlanText?: boolean;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "linkany",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "linkany": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc && node ./scripts/postbuild-shebang.mjs",
+    "test": "vitest"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "Unlicense",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lbb00/linkany.git"
+  },
+  "dependencies": {
+    "fs-extra": "^11.3.3"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^25.0.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  },
+  "packageManager": "pnpm@9.15.3+sha512.1f79bc245a66eb0b07c5d4d83131240774642caaa86ef7d0434ab47c0d16f66b04e21e0c086eb61e62c77efc4d7f7ec071afad3796af64892fae66509173893a"
+}