@chronicle.app/shell 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Louis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,9 @@
+# @chronicle.app/shell
+
+`ShellHistoryExtractor` reads bash, zsh, and fish histories; `ShellHistoryTransformer` emits ExecuteAction/Command records with the local username and machine realm. Pass `input` and optionally `shell` (`auto`, `bash`, `zsh`, `fish`). With an explicit file, auto-detection examines that file; otherwise standard history paths are used. Transformer config can override `username` and `hostname` for exported histories.
+
+Records are yielded in reverse file order; limits apply after inclusive `since`/`until` filtering. `limit: 0` is unlimited. Untimestamped or malformed-time entries remain available as raw records (unless a time window is requested), but do not become fabricated dated actions. No commands from history are executed.
+
+The unified extractor replaces the old deprecated Bash/Zsh classes. It reads the file in memory. Multiline shell syntax is not reconstructed; use raw records when the history format does not provide one complete command per entry.
+
+Tests use temporary history files and an explicit fixture identity, never personal history.

package/dist/connectors/ShellHistoryExtractor.d.ts

@@ -0,0 +1,46 @@
+import { Extractor, Record } from '@chronicle.app/etl';
+import { z } from 'zod';
+import ShellHistoryTransformer from './ShellHistoryTransformer.js';
+export declare class ShellHistoryExtractor extends Extractor<typeof ShellHistoryExtractor> {
+    static source: string;
+    static description: string;
+    static delivery: "local";
+    static strategy: string;
+    static recordTypes: string[];
+    static default: boolean;
+    static defaultTransformer: typeof ShellHistoryTransformer;
+    static schema: z.ZodObject<{
+        since: z.ZodOptional<z.ZodDate>;
+        until: z.ZodOptional<z.ZodDate>;
+        limit: z.ZodOptional<z.ZodNumber>;
+    } & {
+        shell: z.ZodDefault<z.ZodEnum<["auto", "zsh", "bash", "fish"]>>;
+        input: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        shell: "auto" | "zsh" | "bash" | "fish";
+        input?: string | undefined;
+        since?: Date | undefined;
+        until?: Date | undefined;
+        limit?: number | undefined;
+    }, {
+        shell?: "auto" | "zsh" | "bash" | "fish" | undefined;
+        input?: string | undefined;
+        since?: Date | undefined;
+        until?: Date | undefined;
+        limit?: number | undefined;
+    }>;
+    private detectShellType;
+    private getDefaultHistoryPath;
+    extract(): AsyncGenerator<Record>;
+    /**
+     * Yield parsed entries newest-first so `--limit` caps the most recent
+     * commands. History files are append-only logs (oldest at the top), so
+     * this is a reversal of file order.
+     */
+    private yieldNewestFirst;
+    private parseZshHistory;
+    private parseBashHistory;
+    private parseFishHistory;
+    determineCount(): Promise<number | null>;
+}
+//# sourceMappingURL=ShellHistoryExtractor.d.ts.map

package/dist/connectors/ShellHistoryExtractor.js

@@ -0,0 +1,291 @@
+import { Extractor } from '@chronicle.app/etl';
+import { readFile, access } from 'node:fs/promises';
+import { z } from 'zod';
+import os from 'node:os';
+import path from 'node:path';
+import ShellHistoryTransformer from './ShellHistoryTransformer.js';
+const SUPPORTED_SHELLS = ['auto', 'zsh', 'bash', 'fish'];
+export class ShellHistoryExtractor extends Extractor {
+    static source = 'shell';
+    static description = 'Command history (bash, zsh, or fish, auto-detected)';
+    static delivery = 'local';
+    static strategy = 'history';
+    static recordTypes = ['commands'];
+    static default = true;
+    static defaultTransformer = ShellHistoryTransformer;
+    static schema = Extractor.schema.extend({
+        shell: z
+            .enum(SUPPORTED_SHELLS)
+            .default('auto')
+            .describe('Shell type to extract from (auto-detects if not specified)'),
+        input: z
+            .string()
+            .optional()
+            .describe('Path to the shell history file (auto-detects based on shell type if not specified)'),
+    });
+    async detectShellType() {
+        if (this.config.input) {
+            const content = await readFile(this.config.input, 'utf8');
+            if (/^: \d+:\d+;/m.test(content))
+                return 'zsh';
+            if (/^- cmd: /m.test(content))
+                return 'fish';
+            if (/^#\d+$/m.test(content))
+                return 'bash';
+            return path.basename(this.config.input).includes('zsh') ? 'zsh' : 'bash';
+        }
+        const homeDir = os.homedir();
+        // Check for common shell history files in order of preference
+        const shellChecks = [
+            { shell: 'zsh', path: path.join(homeDir, '.zsh_history') },
+            { shell: 'bash', path: path.join(homeDir, '.bash_history') },
+            {
+                shell: 'fish',
+                path: path.join(homeDir, '.local/share/fish/fish_history'),
+            },
+        ];
+        for (const { shell, path: filePath } of shellChecks) {
+            try {
+                await access(filePath);
+                return shell;
+            }
+            catch {
+                // File doesn't exist, continue to next
+            }
+        }
+        // Fallback to environment variable or default to zsh
+        const shellEnv = process.env.SHELL?.toLowerCase() || '';
+        if (shellEnv.includes('zsh'))
+            return 'zsh';
+        if (shellEnv.includes('bash'))
+            return 'bash';
+        if (shellEnv.includes('fish'))
+            return 'fish';
+        // Default fallback
+        return 'zsh';
+    }
+    getDefaultHistoryPath(shellType) {
+        const homeDir = os.homedir();
+        switch (shellType) {
+            case 'zsh':
+                return path.join(homeDir, '.zsh_history');
+            case 'bash':
+                return path.join(homeDir, '.bash_history');
+            case 'fish':
+                return path.join(homeDir, '.local/share/fish/fish_history');
+            default:
+                return path.join(homeDir, '.zsh_history');
+        }
+    }
+    async *extract() {
+        const config = this.config;
+        // Determine shell type
+        const shellType = config.shell === 'auto' ? await this.detectShellType() : config.shell;
+        // Determine input file path
+        const inputPath = config.input || this.getDefaultHistoryPath(shellType);
+        try {
+            const content = await readFile(inputPath, 'utf-8');
+            // Delegate to appropriate parser
+            switch (shellType) {
+                case 'zsh':
+                    yield* this.parseZshHistory(content, inputPath);
+                    break;
+                case 'bash':
+                    yield* this.parseBashHistory(content, inputPath);
+                    break;
+                case 'fish':
+                    yield* this.parseFishHistory(content, inputPath);
+                    break;
+                default:
+                    throw new Error(`Unsupported shell type: ${shellType}`);
+            }
+        }
+        catch (error) {
+            throw new Error(`Failed to read ${shellType} history file from ${inputPath}: ${error}`);
+        }
+    }
+    /**
+     * Yield parsed entries newest-first so `--limit` caps the most recent
+     * commands. History files are append-only logs (oldest at the top), so
+     * this is a reversal of file order.
+     */
+    async *yieldNewestFirst(entries) {
+        let commandCount = 0;
+        for (let i = entries.length - 1; i >= 0; i--) {
+            if (this.shouldStopExtracting(commandCount))
+                break;
+            const { data, metadata } = entries[i];
+            if (this.config.since || this.config.until) {
+                if (!data.timestamp)
+                    continue;
+                const time = new Date(data.timestamp).getTime();
+                if (this.config.since && time < this.config.since.getTime())
+                    continue;
+                if (this.config.until && time > this.config.until.getTime())
+                    continue;
+            }
+            yield this.createRecord(data, metadata);
+            commandCount++;
+        }
+    }
+    async *parseZshHistory(content, inputPath) {
+        const lines = content.split('\n').filter(line => line.trim());
+        const entries = [];
+        for (const [index, line] of lines.entries()) {
+            if (!line.trim())
+                continue;
+            // Parse zsh extended history format: : <timestamp>:<elapsed>;<command>
+            const zshExtendedMatch = line.match(/^: (\d+):\d+;(.*)$/);
+            let command;
+            let timestamp;
+            if (zshExtendedMatch) {
+                const [, timestampStr, cmd] = zshExtendedMatch;
+                const parsedTimestamp = Number.parseInt(timestampStr, 10);
+                if (Number.isNaN(parsedTimestamp)) {
+                    timestamp = null;
+                }
+                else {
+                    try {
+                        timestamp = new Date(parsedTimestamp * 1000).toISOString();
+                    }
+                    catch {
+                        timestamp = null;
+                    }
+                }
+                command = cmd.trim();
+            }
+            else {
+                command = line.trim();
+                timestamp = null;
+            }
+            if (!command)
+                continue;
+            entries.push({
+                data: {
+                    command,
+                    timestamp,
+                    originalLine: line,
+                    shell: 'zsh',
+                    historyFile: inputPath,
+                },
+                metadata: {
+                    lineNumber: index + 1,
+                    hasTimestamp: zshExtendedMatch !== null,
+                    format: zshExtendedMatch ? 'extended' : 'simple',
+                },
+            });
+        }
+        yield* this.yieldNewestFirst(entries);
+    }
+    async *parseBashHistory(content, inputPath) {
+        const lines = content.split('\n').filter(line => line.trim());
+        let currentTimestamp = null;
+        const entries = [];
+        for (const [index, line] of lines.entries()) {
+            if (!line.trim())
+                continue;
+            // Check if this is a timestamp line (starts with #)
+            if (line.startsWith('#')) {
+                const timestampStr = line.slice(1);
+                const parsedTimestamp = /^\d+$/.test(timestampStr) ? Number(timestampStr) : Number.NaN;
+                currentTimestamp = Number.isNaN(parsedTimestamp) ? null : parsedTimestamp;
+                continue;
+            }
+            const command = line.trim();
+            // Create timestamp
+            let timestamp;
+            if (currentTimestamp !== null && !Number.isNaN(currentTimestamp)) {
+                try {
+                    timestamp = new Date(currentTimestamp * 1000).toISOString();
+                }
+                catch {
+                    timestamp = null;
+                }
+            }
+            else {
+                timestamp = null;
+            }
+            entries.push({
+                data: {
+                    command,
+                    timestamp,
+                    originalLine: line,
+                    shell: 'bash',
+                    historyFile: inputPath,
+                },
+                metadata: {
+                    lineNumber: index + 1,
+                    hasTimestamp: currentTimestamp !== null,
+                },
+            });
+        }
+        yield* this.yieldNewestFirst(entries);
+    }
+    async *parseFishHistory(content, inputPath) {
+        const lines = content.split('\n').filter(line => line.trim());
+        const entries = [];
+        let currentCommand = '';
+        let currentTimestamp = null;
+        for (const [index, line] of lines.entries()) {
+            if (!line.trim())
+                continue;
+            if (line.startsWith('- cmd: ')) {
+                currentCommand = line.slice(7); // Remove "- cmd: "
+            }
+            else if (line.startsWith('  when: ')) {
+                const timestampStr = line.slice(8); // Remove "  when: "
+                const parsedTimestamp = Number.parseInt(timestampStr, 10);
+                try {
+                    currentTimestamp = new Date(parsedTimestamp * 1000).toISOString();
+                }
+                catch {
+                    currentTimestamp = null;
+                }
+                // We have both command and timestamp, record the entry
+                if (currentCommand) {
+                    entries.push({
+                        data: {
+                            command: currentCommand,
+                            timestamp: currentTimestamp,
+                            originalLine: `${currentCommand} (${currentTimestamp})`,
+                            shell: 'fish',
+                            historyFile: inputPath,
+                        },
+                        metadata: {
+                            lineNumber: index + 1,
+                            hasTimestamp: true,
+                        },
+                    });
+                    currentCommand = '';
+                    currentTimestamp = null;
+                }
+            }
+        }
+        yield* this.yieldNewestFirst(entries);
+    }
+    async determineCount() {
+        const config = this.config;
+        try {
+            const shellType = config.shell === 'auto' ? await this.detectShellType() : config.shell;
+            const inputPath = config.input || this.getDefaultHistoryPath(shellType);
+            const content = await readFile(inputPath, 'utf-8');
+            const lines = content.split('\n').filter(line => line.trim());
+            switch (shellType) {
+                case 'zsh':
+                    return lines.filter(line => {
+                        const trimmed = line.trim();
+                        return trimmed && (trimmed.match(/^: \d+:\d+;/) || !trimmed.startsWith(':'));
+                    }).length;
+                case 'bash':
+                    return lines.filter(line => !line.startsWith('#')).length;
+                case 'fish':
+                    return lines.filter(line => line.startsWith('- cmd: ')).length;
+                default:
+                    return lines.length;
+            }
+        }
+        catch {
+            return null;
+        }
+    }
+}

package/dist/connectors/ShellHistoryTransformer.d.ts

@@ -0,0 +1,9 @@
+import { ChronicleTransformer, Record } from '@chronicle.app/etl';
+import { ActionAndChildren } from '@chronicle.app/schema';
+export default class ShellHistoryTransformer extends ChronicleTransformer {
+    transform(record: Record): Promise<ActionAndChildren[]>;
+    private buildCommandActions;
+    private buildUser;
+    private buildCommand;
+}
+//# sourceMappingURL=ShellHistoryTransformer.d.ts.map

package/dist/connectors/ShellHistoryTransformer.js

@@ -0,0 +1,69 @@
+import { hostname, userInfo } from 'node:os';
+import { ChronicleTransformer } from '@chronicle.app/etl';
+export default class ShellHistoryTransformer extends ChronicleTransformer {
+    async transform(record) {
+        const actions = [];
+        if (record.extraction.recordType === 'commands') {
+            actions.push(...(await this.buildCommandActions(record)));
+        }
+        return actions;
+    }
+    async buildCommandActions(record) {
+        // The timestamp is part of the key, so it must be stable across
+        // re-extractions — pass through what the extractor asserted, never stamp
+        // one here (a transform-time clock would mint a new CID every run). A
+        // record without a parseable timestamp is dropped rather than fabricated.
+        const timestamp = new Date(record.data.timestamp ?? Number.NaN);
+        if (Number.isNaN(timestamp.getTime()))
+            return [];
+        const executeAction = {
+            '@type': 'ExecuteAction',
+            timestamp,
+            '@key': [
+                '@type',
+                'source',
+                'timestamp',
+                'object.body',
+                'agent.handle',
+                'agent.memberOf[*].handle',
+            ],
+            source: 'shell',
+            agent: await this.buildUser(),
+            object: this.buildCommand(record.data),
+        };
+        return [executeAction];
+    }
+    async buildUser() {
+        // The user account, keyed by its username within the realm (the host) it
+        // belongs to — reached by traversing `memberOf` to the realm's handle, so
+        // the key is (username, machine) without a denormalized namespace scalar.
+        // `sameAs: ['@me']` still merges it onto the account owner. Only the stable
+        // machine name (from SystemInfo) is kept — not the full hostname, which
+        // flips with Tailscale/Bonjour and would thrash a re-observed `name`.
+        // The logical machine as a name-keyed :Realm — folds with the same host seen
+        // by other sources (e.g. Timing, where it also carries the hardware Device
+        // that links to it via inRealm).
+        const realm = {
+            '@type': 'Realm',
+            '@key': ['@type', 'source', 'handle'],
+            source: 'hostname',
+            handle: (this.config.hostname ?? hostname()).trim().split('.')[0].toLowerCase(),
+        };
+        return {
+            '@type': 'Person',
+            '@key': ['@type', 'source', 'handle', 'memberOf[*].handle'],
+            source: 'shell',
+            handle: this.config.username ?? userInfo().username,
+            memberOf: [realm],
+            sameAs: ['@me'],
+        };
+    }
+    buildCommand(data) {
+        return {
+            '@type': 'Command',
+            '@key': ['@type', 'source', 'body', 'action.timestamp'],
+            source: 'shell',
+            body: data.command,
+        };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { ShellHistoryExtractor } from './connectors/ShellHistoryExtractor.js';
+export { default as ShellHistoryTransformer } from './connectors/ShellHistoryTransformer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,2 @@
+export { ShellHistoryExtractor } from './connectors/ShellHistoryExtractor.js';
+export { default as ShellHistoryTransformer } from './connectors/ShellHistoryTransformer.js';

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@chronicle.app/shell",
+  "version": "0.1.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts"
+  ],
+  "scripts": {
+    "build": "tsc -b tsconfig.lib.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "lint": "eslint src --ext .ts,.js",
+    "test": "node --test src/*.test.js"
+  },
+  "keywords": [],
+  "author": "Andrew Louis",
+  "license": "MIT",
+  "type": "module",
+  "description": "Chronicle shell extraction plugin",
+  "devDependencies": {
+    "@chronicle.app/tsconfig": "0.1.0",
+    "@types/node": "^22.10.1",
+    "typescript": "^5.7.2"
+  },
+  "homepage": "https://chronicle.app",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chronicle-app/chronicle.git",
+    "directory": "plugins/shell"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@chronicle.app/etl": "0.1.0",
+    "@chronicle.app/schema": "0.1.0",
+    "zod": "^3.24.1"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "chronicle": {
+    "plugin": true
+  },
+  "oclif": {}
+}