@elaraai/e3-cli 0.0.2-beta.9 → 1.0.1

package/dist/src/commands/complete.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+export declare function completeCommand(cwordStr: string, words?: string[]): Promise<void>;
+/**
+ * Pure(-ish) helper that produces the candidate list for given inputs.
+ *
+ * Static branches never touch the network or filesystem. Dynamic branches
+ * (workspace / dataset path completion) may call out to local storage or
+ * the API client — wrapped in try/catch so completion never errors.
+ */
+export declare function completionCandidates(cwordStr: string, words: string[]): Promise<string[]>;
+//# sourceMappingURL=complete.d.ts.map

package/dist/src/commands/complete.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"complete.d.ts","sourceRoot":"","sources":["../../../src/commands/complete.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAoDH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,GAAE,MAAM,EAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAI3F;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAuB/F"}

package/dist/src/commands/complete.js

@@ -0,0 +1,166 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * Hidden `e3 __complete <cword> <words...>` handler.
+ *
+ * Called by the shell completion scripts. Given the position of the cursor
+ * and the words on the command line (excluding the leading `e3`), prints
+ * newline-separated candidates that the shell uses to populate completion.
+ *
+ * Static candidates (subcommand names, flag names, enum values) are returned
+ * immediately. Dynamic candidates (workspace names, dataset paths) query the
+ * relevant list functions; errors are swallowed silently so the shell never
+ * sees noise from a missing repo or unreachable server.
+ */
+import { workspaceList, LocalStorage } from '@elaraai/e3-core';
+import { workspaceList as workspaceListRemote } from '@elaraai/e3-api-client';
+import { parseRepoLocation, defaultRepoArg } from '../utils.js';
+import { buildWorkspaceIndex } from '../path-resolver.js';
+// =============================================================================
+// Static tables
+// =============================================================================
+/** Top-level subcommand names. */
+const TOP_LEVEL = [
+    'repo', 'package', 'workspace', 'dataset', 'task', 'dataflow', 'auth',
+    'run', 'watch', 'convert', 'completion',
+];
+/** Subcommand names per noun group. */
+const SUBCOMMANDS = {
+    repo: ['create', 'remove', 'status', 'gc', 'list'],
+    package: ['import', 'export', 'list', 'remove'],
+    workspace: ['create', 'remove', 'list', 'status', 'deploy', 'export'],
+    dataset: ['get', 'set', 'list', 'status', 'find'],
+    task: ['logs', 'list'],
+    dataflow: ['run'],
+    auth: ['login', 'logout', 'status', 'token', 'whoami'],
+    completion: ['bash', 'zsh', 'fish'],
+};
+/** Enum values for known options. */
+const FORMAT_VALUES = ['east', 'json', 'beast2'];
+/** Number of dynamic candidates to emit at most. */
+const MAX_DYNAMIC_CANDIDATES = 100;
+// =============================================================================
+// Entry point (commander action wrapper)
+// =============================================================================
+export async function completeCommand(cwordStr, words = []) {
+    for (const c of await completionCandidates(cwordStr, words)) {
+        console.log(c);
+    }
+}
+/**
+ * Pure(-ish) helper that produces the candidate list for given inputs.
+ *
+ * Static branches never touch the network or filesystem. Dynamic branches
+ * (workspace / dataset path completion) may call out to local storage or
+ * the API client — wrapped in try/catch so completion never errors.
+ */
+export async function completionCandidates(cwordStr, words) {
+    const cword = Number.parseInt(cwordStr, 10);
+    if (!Number.isInteger(cword) || cword < 0)
+        return [];
+    const current = words[cword] ?? '';
+    const prev = cword > 0 ? words[cword - 1] : '';
+    if (prev === '--format' || prev === '-f') {
+        return filterByPrefix(FORMAT_VALUES, current);
+    }
+    if (cword === 0) {
+        return filterByPrefix(TOP_LEVEL, current);
+    }
+    const cmd = words[0];
+    if (cword === 1 && SUBCOMMANDS[cmd]) {
+        return filterByPrefix(SUBCOMMANDS[cmd], current);
+    }
+    const sub = words[1] ?? '';
+    return dispatchPositional(cmd, sub, cword, words, current);
+}
+// =============================================================================
+// Positional dispatcher
+// =============================================================================
+async function dispatchPositional(cmd, sub, cword, words, current) {
+    // For all noun groups, `<cmd> <sub> <repo> [more...]` puts the repo at index 2.
+    const repoIndex = 2;
+    if (cword === repoIndex) {
+        return filterByPrefix(['.', 'http://', 'https://'], current);
+    }
+    // dataset.{get,set,status}: third positional is the dotted dataset path.
+    if (cmd === 'dataset' && (sub === 'get' || sub === 'set' || sub === 'status') && cword === repoIndex + 1) {
+        return completeDatasetPath(words[repoIndex], current);
+    }
+    // dataset.{list,find}: third positional is the workspace name.
+    if (cmd === 'dataset' && (sub === 'list' || sub === 'find') && cword === repoIndex + 1) {
+        return completeWorkspaceName(words[repoIndex], current);
+    }
+    // task.list / dataflow.run: third positional is the workspace name.
+    if ((cmd === 'task' && sub === 'list') ||
+        (cmd === 'dataflow' && sub === 'run')) {
+        if (cword === repoIndex + 1) {
+            return completeWorkspaceName(words[repoIndex], current);
+        }
+    }
+    // task.logs: third positional is the dotted task path.
+    if (cmd === 'task' && sub === 'logs' && cword === repoIndex + 1) {
+        return completeDatasetPath(words[repoIndex], current);
+    }
+    // workspace.{remove,status,export,deploy}: third positional is the ws name.
+    if (cmd === 'workspace' &&
+        (sub === 'remove' || sub === 'status' || sub === 'export' || sub === 'deploy') &&
+        cword === repoIndex + 1) {
+        return completeWorkspaceName(words[repoIndex], current);
+    }
+    return [];
+}
+// =============================================================================
+// Dynamic candidates
+// =============================================================================
+async function completeWorkspaceName(repoArg, current) {
+    try {
+        const location = await parseRepoLocation(defaultRepoArg(repoArg));
+        const names = location.type === 'local'
+            ? await workspaceList(new LocalStorage(), location.path)
+            : (await workspaceListRemote(location.baseUrl, location.repo, { token: location.token }))
+                .map((w) => w.name);
+        return filterByPrefix(names, current);
+    }
+    catch {
+        return [];
+    }
+}
+async function completeDatasetPath(repoArg, current) {
+    // The current word looks like `<ws>` or `<ws>.<prefix>`. With no dot, suggest
+    // workspace names with a trailing dot to invite drill-down; with a dot,
+    // suggest dataset names under that workspace.
+    try {
+        const location = await parseRepoLocation(defaultRepoArg(repoArg));
+        const dotIdx = current.indexOf('.');
+        if (dotIdx === -1) {
+            const wsNames = location.type === 'local'
+                ? await workspaceList(new LocalStorage(), location.path)
+                : (await workspaceListRemote(location.baseUrl, location.repo, { token: location.token }))
+                    .map((w) => w.name);
+            return filterByPrefix(wsNames.map((w) => `${w}.`), current);
+        }
+        const ws = current.slice(0, dotIdx);
+        const index = await buildWorkspaceIndex(location, ws);
+        return filterByPrefix(index.map((e) => `${ws}.${e.name}`), current);
+    }
+    catch {
+        return [];
+    }
+}
+// =============================================================================
+// Filter
+// =============================================================================
+function filterByPrefix(candidates, current) {
+    const out = [];
+    for (const c of candidates) {
+        if (!c.startsWith(current))
+            continue;
+        out.push(c);
+        if (out.length >= MAX_DYNAMIC_CANDIDATES)
+            break;
+    }
+    return out;
+}
+//# sourceMappingURL=complete.js.map

package/dist/src/commands/complete.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"complete.js","sourceRoot":"","sources":["../../../src/commands/complete.ts"],"names":[],"mappings":"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"}

package/dist/src/commands/complete.spec.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+export {};
+//# sourceMappingURL=complete.spec.d.ts.map

package/dist/src/commands/complete.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"complete.spec.d.ts","sourceRoot":"","sources":["../../../src/commands/complete.spec.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/src/commands/complete.spec.js

@@ -0,0 +1,63 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { completionCandidates } from './complete.js';
+/**
+ * The static branches of `completionCandidates` are exercised here.
+ * Dynamic branches (workspace/dataset path lookups) hit storage or the API,
+ * which is covered by integration tests.
+ */
+describe('completionCandidates — static', () => {
+    it('returns top-level commands when cword=0', async () => {
+        const c = await completionCandidates('0', ['']);
+        assert.ok(c.includes('dataset'));
+        assert.ok(c.includes('workspace'));
+        assert.ok(c.includes('completion'));
+    });
+    it('filters top-level commands by prefix', async () => {
+        const c = await completionCandidates('0', ['dat']);
+        assert.deepStrictEqual(c, ['dataset', 'dataflow']);
+    });
+    it('returns nothing for unknown numeric cword string', async () => {
+        assert.deepStrictEqual(await completionCandidates('xyz', []), []);
+        assert.deepStrictEqual(await completionCandidates('-1', []), []);
+    });
+    it('returns subcommands for a known noun at cword=1', async () => {
+        const c = await completionCandidates('1', ['dataset', '']);
+        assert.deepStrictEqual(c.sort(), ['find', 'get', 'list', 'set', 'status']);
+    });
+    it('filters subcommands by prefix', async () => {
+        const c = await completionCandidates('1', ['dataset', 'g']);
+        assert.deepStrictEqual(c, ['get']);
+    });
+    it('returns empty for unknown noun at cword=1', async () => {
+        assert.deepStrictEqual(await completionCandidates('1', ['nosuch', '']), []);
+    });
+    it('suggests format enum after --format', async () => {
+        const c = await completionCandidates('5', ['dataset', 'get', '.', 'dev.greet', '--format', '']);
+        assert.deepStrictEqual(c, ['east', 'json', 'beast2']);
+    });
+    it('filters format enum by prefix', async () => {
+        const c = await completionCandidates('5', ['dataset', 'get', '.', 'dev.greet', '--format', 'j']);
+        assert.deepStrictEqual(c, ['json']);
+    });
+    it('suggests repo seeds at the repo slot', async () => {
+        const c = await completionCandidates('2', ['dataset', 'get', '']);
+        assert.ok(c.includes('.'));
+        assert.ok(c.includes('http://'));
+        assert.ok(c.includes('https://'));
+    });
+    it('filters repo seeds by prefix', async () => {
+        const c = await completionCandidates('2', ['dataset', 'get', 'http']);
+        assert.deepStrictEqual(c.sort(), ['http://', 'https://']);
+    });
+    it('returns empty when no rule matches a position', async () => {
+        // cword beyond known shape and no special rule
+        const c = await completionCandidates('5', ['convert', 'file.east', '--from', 'east', '--to', '']);
+        assert.deepStrictEqual(c, []);
+    });
+});
+//# sourceMappingURL=complete.spec.js.map

package/dist/src/commands/complete.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"complete.spec.js","sourceRoot":"","sources":["../../../src/commands/complete.spec.ts"],"names":[],"mappings":"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"}

package/dist/src/commands/completion-install.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+export type SupportedShell = 'bash' | 'zsh' | 'fish';
+interface InstallOptions {
+    shell?: string;
+    quiet?: boolean;
+}
+interface UninstallOptions {
+    shell?: string;
+}
+/**
+ * Detect the user's interactive shell from $SHELL.
+ *
+ * Returns `null` when $SHELL is unset or unrecognised.
+ */
+export declare function detectShell(env?: NodeJS.ProcessEnv): SupportedShell | null;
+/**
+ * Resolve the file to edit for a given shell.
+ *
+ * bash → ~/.bashrc, zsh → ~/.zshrc (honouring $ZDOTDIR),
+ * fish → ~/.config/fish/completions/e3.fish (a file, not appended to rc).
+ */
+export declare function rcPath(shell: SupportedShell, env?: NodeJS.ProcessEnv, home?: string): string;
+/**
+ * Install completion for the chosen (or detected) shell.
+ *
+ * Behaviour matrix:
+ *   - fish  : writes ~/.config/fish/completions/e3.fish (overwrites)
+ *   - bash  : appends `eval "$(e3 completion bash)" {MARKER}` to ~/.bashrc
+ *   - zsh   : same as bash but for ~/.zshrc
+ *
+ * Both bash and zsh paths short-circuit if the marker is already present, so
+ * re-running this command is a no-op.
+ */
+export declare function installCommand(options?: InstallOptions): void;
+/** Pure helper for install — exposed for tests via a real filesystem path. */
+export declare function installToFile(shell: SupportedShell, target: string): string;
+/**
+ * Uninstall completion for the chosen (or detected) shell.
+ */
+export declare function uninstallCommand(options?: UninstallOptions): void;
+/** Pure helper for uninstall — exposed for tests. */
+export declare function uninstallFromFile(shell: SupportedShell, target: string): string;
+export {};
+//# sourceMappingURL=completion-install.d.ts.map

package/dist/src/commands/completion-install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion-install.d.ts","sourceRoot":"","sources":["../../../src/commands/completion-install.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAwBH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;AAKrD,UAAU,cAAc;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,UAAU,gBAAgB;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,cAAc,GAAG,IAAI,CAQvF;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,EAAE,IAAI,GAAE,MAAkB,GAAG,MAAM,CASpH;AAgBD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,OAAO,GAAE,cAAmB,GAAG,IAAI,CAWjE;AAED,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAiB3E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,gBAAqB,GAAG,IAAI,CAQrE;AAED,qDAAqD;AACrD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAqB/E"}

package/dist/src/commands/completion-install.js

@@ -0,0 +1,141 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * `e3 completion install` / `e3 completion uninstall`.
+ *
+ * Edits the user's shell rc file (bash, zsh) or writes a completion file (fish).
+ * Idempotent: re-running `install` doesn't duplicate the eval line; `uninstall`
+ * removes only the marker line we control.
+ *
+ * Used by the `postinstall` hook on `npm install -g` and by `make link`.
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { COMPLETION_SCRIPTS } from './completion.js';
+import { exitError, formatError } from '../utils.js';
+const MARKER = '# e3 completion';
+const SHELLS = ['bash', 'zsh', 'fish'];
+/**
+ * Detect the user's interactive shell from $SHELL.
+ *
+ * Returns `null` when $SHELL is unset or unrecognised.
+ */
+export function detectShell(env = process.env) {
+    const shell = env.SHELL;
+    if (!shell)
+        return null;
+    const basename = shell.split('/').pop() ?? '';
+    if (basename === 'bash')
+        return 'bash';
+    if (basename === 'zsh')
+        return 'zsh';
+    if (basename === 'fish')
+        return 'fish';
+    return null;
+}
+/**
+ * Resolve the file to edit for a given shell.
+ *
+ * bash → ~/.bashrc, zsh → ~/.zshrc (honouring $ZDOTDIR),
+ * fish → ~/.config/fish/completions/e3.fish (a file, not appended to rc).
+ */
+export function rcPath(shell, env = process.env, home = homedir()) {
+    switch (shell) {
+        case 'bash':
+            return join(home, '.bashrc');
+        case 'zsh':
+            return env.ZDOTDIR ? join(env.ZDOTDIR, '.zshrc') : join(home, '.zshrc');
+        case 'fish':
+            return join(home, '.config', 'fish', 'completions', 'e3.fish');
+    }
+}
+function resolveShell(shell) {
+    if (shell !== undefined) {
+        if (!SHELLS.includes(shell)) {
+            exitError(`Unknown shell: '${shell}'. Use one of: ${SHELLS.join(', ')}`);
+        }
+        return shell;
+    }
+    const detected = detectShell();
+    if (detected)
+        return detected;
+    exitError(`Could not detect shell from $SHELL. Specify explicitly with --shell ${SHELLS.join('|')}`);
+}
+/**
+ * Install completion for the chosen (or detected) shell.
+ *
+ * Behaviour matrix:
+ *   - fish  : writes ~/.config/fish/completions/e3.fish (overwrites)
+ *   - bash  : appends `eval "$(e3 completion bash)" {MARKER}` to ~/.bashrc
+ *   - zsh   : same as bash but for ~/.zshrc
+ *
+ * Both bash and zsh paths short-circuit if the marker is already present, so
+ * re-running this command is a no-op.
+ */
+export function installCommand(options = {}) {
+    try {
+        const shell = resolveShell(options.shell);
+        const target = rcPath(shell);
+        const result = installToFile(shell, target);
+        if (!options.quiet) {
+            console.log(result);
+        }
+    }
+    catch (err) {
+        exitError(formatError(err));
+    }
+}
+/** Pure helper for install — exposed for tests via a real filesystem path. */
+export function installToFile(shell, target) {
+    if (shell === 'fish') {
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, COMPLETION_SCRIPTS.fish);
+        return `Installed fish completion: ${target}`;
+    }
+    const evalLine = `eval "$(e3 completion ${shell})"  ${MARKER}`;
+    const content = existsSync(target) ? readFileSync(target, 'utf-8') : '';
+    if (content.includes(MARKER)) {
+        return `e3 completion already installed in ${target}`;
+    }
+    const sep = content.length === 0 || content.endsWith('\n') ? '' : '\n';
+    writeFileSync(target, `${content}${sep}${evalLine}\n`);
+    return `Installed ${shell} completion in ${target}\nRestart your shell, or run: source ${target}`;
+}
+/**
+ * Uninstall completion for the chosen (or detected) shell.
+ */
+export function uninstallCommand(options = {}) {
+    try {
+        const shell = resolveShell(options.shell);
+        const target = rcPath(shell);
+        console.log(uninstallFromFile(shell, target));
+    }
+    catch (err) {
+        exitError(formatError(err));
+    }
+}
+/** Pure helper for uninstall — exposed for tests. */
+export function uninstallFromFile(shell, target) {
+    if (shell === 'fish') {
+        if (!existsSync(target)) {
+            return `No completion file at ${target}`;
+        }
+        unlinkSync(target);
+        return `Removed ${target}`;
+    }
+    if (!existsSync(target)) {
+        return `No rc file at ${target}`;
+    }
+    const content = readFileSync(target, 'utf-8');
+    const lines = content.split('\n');
+    const filtered = lines.filter((l) => !l.includes(MARKER));
+    if (filtered.length === lines.length) {
+        return `e3 completion not present in ${target}`;
+    }
+    writeFileSync(target, filtered.join('\n'));
+    return `Removed e3 completion from ${target}`;
+}
+//# sourceMappingURL=completion-install.js.map

package/dist/src/commands/completion-install.js.map

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

package/dist/src/commands/completion-install.spec.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+export {};
+//# sourceMappingURL=completion-install.spec.d.ts.map

package/dist/src/commands/completion-install.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion-install.spec.d.ts","sourceRoot":"","sources":["../../../src/commands/completion-install.spec.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/src/commands/completion-install.spec.js

@@ -0,0 +1,136 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { detectShell, rcPath, installToFile, uninstallFromFile } from './completion-install.js';
+let tmp;
+before(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'e3-completion-test-'));
+});
+after(() => {
+    rmSync(tmp, { recursive: true, force: true });
+});
+describe('detectShell', () => {
+    it('detects bash from /bin/bash', () => {
+        assert.strictEqual(detectShell({ SHELL: '/bin/bash' }), 'bash');
+    });
+    it('detects zsh from /usr/bin/zsh', () => {
+        assert.strictEqual(detectShell({ SHELL: '/usr/bin/zsh' }), 'zsh');
+    });
+    it('detects fish from /usr/local/bin/fish', () => {
+        assert.strictEqual(detectShell({ SHELL: '/usr/local/bin/fish' }), 'fish');
+    });
+    it('returns null for unknown shells', () => {
+        assert.strictEqual(detectShell({ SHELL: '/bin/dash' }), null);
+    });
+    it('returns null when SHELL is unset', () => {
+        assert.strictEqual(detectShell({}), null);
+    });
+});
+describe('rcPath', () => {
+    it('uses ~/.bashrc for bash', () => {
+        assert.strictEqual(rcPath('bash', {}, '/home/u'), '/home/u/.bashrc');
+    });
+    it('uses ~/.zshrc for zsh by default', () => {
+        assert.strictEqual(rcPath('zsh', {}, '/home/u'), '/home/u/.zshrc');
+    });
+    it('honours $ZDOTDIR for zsh', () => {
+        assert.strictEqual(rcPath('zsh', { ZDOTDIR: '/etc/zsh' }, '/home/u'), '/etc/zsh/.zshrc');
+    });
+    it('uses ~/.config/fish/completions/e3.fish for fish', () => {
+        assert.strictEqual(rcPath('fish', {}, '/home/u'), '/home/u/.config/fish/completions/e3.fish');
+    });
+});
+describe('installToFile — bash/zsh', () => {
+    it('appends the eval line when the file is missing', () => {
+        const target = join(tmp, 'fresh.bashrc');
+        const out = installToFile('bash', target);
+        assert.match(out, /Installed bash completion/);
+        const content = readFileSync(target, 'utf-8');
+        assert.match(content, /eval "\$\(e3 completion bash\)"/);
+        assert.match(content, /# e3 completion/);
+    });
+    it('appends to a non-empty file, preserving prior content', () => {
+        const target = join(tmp, 'existing.bashrc');
+        writeFileSync(target, '# my stuff\nalias ls="ls -lh"\n');
+        installToFile('bash', target);
+        const content = readFileSync(target, 'utf-8');
+        assert.ok(content.startsWith('# my stuff\nalias ls="ls -lh"\n'));
+        assert.match(content, /eval "\$\(e3 completion bash\)"/);
+    });
+    it('is idempotent — re-running does not duplicate the eval line', () => {
+        const target = join(tmp, 'idem.bashrc');
+        installToFile('bash', target);
+        installToFile('bash', target);
+        const content = readFileSync(target, 'utf-8');
+        const evalLines = content.split('\n').filter((l) => l.startsWith('eval "$(e3 completion'));
+        assert.strictEqual(evalLines.length, 1);
+    });
+    it('handles files missing a trailing newline', () => {
+        const target = join(tmp, 'no-newline.bashrc');
+        writeFileSync(target, 'export FOO=1');
+        installToFile('bash', target);
+        const content = readFileSync(target, 'utf-8');
+        assert.match(content, /export FOO=1\neval/);
+    });
+});
+describe('installToFile — fish', () => {
+    it('writes the completion file', () => {
+        const target = join(tmp, 'fish', 'completions', 'e3.fish');
+        const out = installToFile('fish', target);
+        assert.match(out, /Installed fish completion/);
+        assert.ok(existsSync(target));
+        const content = readFileSync(target, 'utf-8');
+        assert.match(content, /e3 fish completion/);
+    });
+    it('overwrites an existing file (no idempotency drama)', () => {
+        const target = join(tmp, 'fish2', 'completions', 'e3.fish');
+        installToFile('fish', target);
+        const first = readFileSync(target, 'utf-8');
+        installToFile('fish', target);
+        const second = readFileSync(target, 'utf-8');
+        assert.strictEqual(first, second);
+    });
+});
+describe('uninstallFromFile — bash/zsh', () => {
+    it('removes the marker line, leaving other content', () => {
+        const target = join(tmp, 'uninst.bashrc');
+        writeFileSync(target, '# my stuff\n');
+        installToFile('bash', target);
+        uninstallFromFile('bash', target);
+        const content = readFileSync(target, 'utf-8');
+        assert.match(content, /# my stuff/);
+        assert.doesNotMatch(content, /e3 completion/);
+    });
+    it('returns a "not present" message when marker missing', () => {
+        const target = join(tmp, 'clean.bashrc');
+        writeFileSync(target, '# nothing here\n');
+        const out = uninstallFromFile('bash', target);
+        assert.match(out, /not present/);
+    });
+    it('returns a "no rc file" message when file is missing', () => {
+        const target = join(tmp, 'does-not-exist');
+        const out = uninstallFromFile('bash', target);
+        assert.match(out, /No rc file/);
+    });
+});
+describe('uninstallFromFile — fish', () => {
+    it('removes the completion file when it exists', () => {
+        const target = join(tmp, 'fish3', 'completions', 'e3.fish');
+        installToFile('fish', target);
+        const out = uninstallFromFile('fish', target);
+        assert.match(out, /Removed/);
+        assert.ok(!existsSync(target));
+    });
+    it('returns a "no file" message when nothing to remove', () => {
+        const target = join(tmp, 'fish4', 'completions', 'e3.fish');
+        const out = uninstallFromFile('fish', target);
+        assert.match(out, /No completion file/);
+    });
+});
+//# sourceMappingURL=completion-install.spec.js.map

package/dist/src/commands/completion-install.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion-install.spec.js","sourceRoot":"","sources":["../../../src/commands/completion-install.spec.ts"],"names":[],"mappings":"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"}