edgar-cli 0.1.3 → 0.2.1

package/README.md

@@ -1,133 +1,11 @@
 # edgar-cli
 
-Agent-friendly SEC EDGAR CLI for filings and company facts.
+Go-native SEC EDGAR CLI for `npx` workflows.
 
-## Features
-
-- `npx`-friendly Node/TypeScript package (no Python runtime needed)
-- JSON envelope output by default for stable automation
-- Strict SEC identity enforcement (`--user-agent` or `EDGAR_USER_AGENT`)
-- Core commands:
-  - `resolve`
-  - `filings list`
-  - `filings get`
-  - `facts get`
-  - `research sync`
-  - `research ask`
-
-## Install / Run
+This package is a small Node launcher that dispatches to a prebuilt native Go binary for the current platform.
 
 ```bash
 npx edgar-cli --help
 ```
 
-Local development:
-
-```bash
-npm install
-npm run build
-node dist/cli.js --help
-```
-
-## SEC Identity Requirement
-
-SEC endpoints require declared automated access identity.
-
-Use either:
-
-```bash
-export EDGAR_USER_AGENT="Your Name your.email@example.com"
-```
-
-Or pass per command:
-
-```bash
-npx edgar-cli --user-agent "Your Name your.email@example.com" resolve AAPL
-```
-
-If identity is missing, commands fail with `IDENTITY_REQUIRED`.
-
-## Examples
-
-```bash
-# Resolve ticker -> canonical SEC identity mapping
-npx edgar-cli --user-agent "Your Name your.email@example.com" resolve AAPL
-
-# List recent 10-K filings
-npx edgar-cli --user-agent "Your Name your.email@example.com" filings list --id AAPL --form 10-K --query-limit 5
-
-# Get filing document URL by accession
-npx edgar-cli --user-agent "Your Name your.email@example.com" filings get --id AAPL --accession 0000320193-26-000006 --format url
-
-# Get filing converted to Markdown
-npx edgar-cli --user-agent "Your Name your.email@example.com" filings get --id AAPL --accession 0000320193-26-000006 --format markdown
-
-# Get concept data (latest per unit)
-npx edgar-cli --user-agent "Your Name your.email@example.com" facts get --id AAPL --taxonomy us-gaap --concept Revenues --latest
-
-# Query explicit local docs (repeat --doc or pass --manifest)
-npx edgar-cli research ask "board resignation details" --doc ./cache/nvda-8k.md --top-k 5
-
-# Build a deterministic cached corpus for a ticker/profile
-npx edgar-cli --user-agent "Your Name your.email@example.com" research sync --id NVDA --profile core
-
-# Query by ticker against cached corpus (auto-syncs on cache miss)
-npx edgar-cli --user-agent "Your Name your.email@example.com" research ask "what changed on the board?" --id NVDA --profile core
-```
-
-## Research Profiles and Cache
-
-`research sync` and `research ask --id` use deterministic filing profiles:
-
-- `core`: latest 1x `10-K`, latest 3x `10-Q`, and recent `8-K` (last 180 days, up to 12)
-- `events`: recent `8-K` (last 365 days, up to 24)
-- `financials`: latest 2x `10-K` and latest 6x `10-Q`
-
-By default, cached corpora are stored in:
-
-- `$EDGAR_CACHE_DIR` (if set), else
-- `$XDG_CACHE_HOME/edgar-cli` (if set), else
-- `~/.cache/edgar-cli`
-
-Override per command with `--cache-dir`.
-
-## Output Contract (default)
-
-All JSON-mode commands emit:
-
-```json
-{
-  "ok": true,
-  "command": "resolve",
-  "provider": "sec",
-  "data": {},
-  "error": null,
-  "meta": {
-    "timestamp": "2026-02-11T00:00:00Z",
-    "output_schema": "v1",
-    "view": "summary"
-  }
-}
-```
-
-## Compliance Notes
-
-- This CLI targets SEC-hosted endpoints only in V0.
-- Respect SEC fair-access guidance and use a valid identity in your user-agent.
-
-References:
-
-- [SEC Developer](https://www.sec.gov/developer)
-- [SEC Webmaster FAQ: code support](https://www.sec.gov/os/webmaster-faq#code-support)
-
-## Security
-
-See [`SECURITY.md`](SECURITY.md) for vulnerability reporting guidance.
-
-## Development
-
-```bash
-npm run typecheck
-npm run test
-npm run build
-```
+See the repository README for command examples and compliance notes.

package/bin/edgar-lib.cjs

@@ -0,0 +1,118 @@
+const { spawnSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const NATIVE_TARGETS = {
+  "darwin-arm64": {
+    packageName: "edgar-cli-darwin-arm64",
+    binaryRelPath: "bin/edgar"
+  },
+  "linux-x64": {
+    packageName: "edgar-cli-linux-x64",
+    binaryRelPath: "bin/edgar"
+  }
+};
+
+function targetKey(platform, arch) {
+  return `${platform}-${arch}`;
+}
+
+function resolveNativeBinary({
+  platform = process.platform,
+  arch = process.arch,
+  requireResolve = require.resolve,
+  exists = fs.existsSync,
+  baseDir = __dirname
+} = {}) {
+  const key = targetKey(platform, arch);
+  const spec = NATIVE_TARGETS[key];
+
+  if (!spec) {
+    return {
+      supported: false,
+      key,
+      packageName: null,
+      binaryPath: null
+    };
+  }
+
+  const localNodeModulesBinary = path.resolve(
+    baseDir,
+    "..",
+    "node_modules",
+    spec.packageName,
+    spec.binaryRelPath
+  );
+  if (exists(localNodeModulesBinary)) {
+    return {
+      supported: true,
+      key,
+      packageName: spec.packageName,
+      binaryPath: localNodeModulesBinary
+    };
+  }
+
+  try {
+    const binaryPath = requireResolve(`${spec.packageName}/${spec.binaryRelPath}`);
+
+    return {
+      supported: true,
+      key,
+      packageName: spec.packageName,
+      binaryPath
+    };
+  } catch (error) {
+    if (error && error.code === "MODULE_NOT_FOUND") {
+      return {
+        supported: true,
+        key,
+        packageName: spec.packageName,
+        binaryPath: null
+      };
+    }
+    throw error;
+  }
+}
+
+function runEdgar({
+  argv,
+  env = process.env,
+  spawn = spawnSync,
+  stderr = process.stderr,
+  platform = process.platform,
+  arch = process.arch,
+  resolveNative = resolveNativeBinary
+}) {
+  const native = resolveNative({ platform, arch });
+
+  if (!native.supported) {
+    stderr.write(`edgar-cli native runtime is not available for ${native.key}.\n`);
+    return 1;
+  }
+
+  if (!native.binaryPath) {
+    stderr.write(`edgar-cli native runtime package missing: ${native.packageName}\n`);
+    stderr.write("Reinstall with optional dependencies enabled, then retry `npx edgar-cli --help`.\n");
+    return 1;
+  }
+
+  const result = spawn(native.binaryPath, argv, { stdio: "inherit", env });
+  if (result.error) {
+    stderr.write(`edgar-cli native launcher failed: ${result.error.message}\n`);
+    return 1;
+  }
+  if (typeof result.status === "number") {
+    return result.status;
+  }
+  if (result.signal) {
+    stderr.write(`edgar-cli native launcher terminated by signal ${result.signal}\n`);
+    return 1;
+  }
+  return 1;
+}
+
+module.exports = {
+  NATIVE_TARGETS,
+  resolveNativeBinary,
+  runEdgar
+};

package/bin/edgar.cjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+const { runEdgar } = require("./edgar-lib.cjs");
+
+const exitCode = runEdgar({ argv: process.argv.slice(2) });
+process.exit(exitCode);

package/package.json

@@ -1,63 +1,49 @@
 {
   "name": "edgar-cli",
-  "version": "0.1.3",
-  "description": "Agent-friendly SEC EDGAR CLI",
+  "version": "0.2.1",
+  "description": "Go-native SEC EDGAR CLI for npx",
   "license": "MIT",
-  "type": "module",
+  "type": "commonjs",
   "publishConfig": {
     "access": "public"
   },
   "bin": {
-    "edgar-cli": "dist/cli.js",
-    "edgar": "dist/cli.js"
+    "edgar-cli": "bin/edgar.cjs",
+    "edgar": "bin/edgar.cjs"
   },
   "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
+    "bin",
+    "README.md"
   ],
   "engines": {
     "node": ">=18"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/finlayi/edgar-cli.git"
+    "url": "git+https://github.com/finlayi/edgar-cli.git",
+    "directory": "npm"
   },
   "homepage": "https://github.com/finlayi/edgar-cli#readme",
   "bugs": {
     "url": "https://github.com/finlayi/edgar-cli/issues"
   },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "dev": "tsx src/cli.ts",
-    "test": "vitest run",
-    "lint": "eslint . --ext .ts",
-    "typecheck": "tsc --noEmit"
-  },
   "keywords": [
     "edgar",
     "sec",
     "cli",
     "npx",
-    "filings"
+    "filings",
+    "go",
+    "native"
   ],
-  "dependencies": {
-    "@joplin/turndown-plugin-gfm": "^1.0.64",
-    "commander": "^14.0.1",
-    "p-limit": "^7.1.1",
-    "turndown": "^7.2.2",
-    "zod": "^4.1.5"
+  "optionalDependencies": {
+    "edgar-cli-darwin-arm64": "0.2.1",
+    "edgar-cli-linux-x64": "0.2.1"
   },
-  "devDependencies": {
-    "@types/node": "^22.13.9",
-    "@types/turndown": "^5.0.6",
-    "@typescript-eslint/eslint-plugin": "^8.44.0",
-    "@typescript-eslint/parser": "^8.44.0",
-    "eslint": "^8.57.1",
-    "nock": "^14.0.10",
-    "prettier": "^3.6.2",
-    "tsx": "^4.20.5",
-    "typescript": "^5.9.2",
-    "vitest": "^3.2.4"
+  "scripts": {
+    "build:native": "node scripts/build-native.cjs",
+    "sync:versions": "node scripts/sync-platform-versions.cjs",
+    "test:versions": "node scripts/sync-platform-versions.cjs --check",
+    "test": "npm run test:versions && node --test test/*.test.cjs"
   }
 }

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Ian Finlay
-
-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/dist/cli.d.ts

@@ -1,10 +0,0 @@
-#!/usr/bin/env node
-import { Command } from 'commander';
-interface CliIo {
-    stdout: (message: string) => void;
-    stderr: (message: string) => void;
-    env: NodeJS.ProcessEnv;
-}
-export declare function buildProgram(io: CliIo): Command;
-export declare function runCli(argv: string[], io?: CliIo): Promise<number>;
-export {};

package/dist/cli.js

@@ -1,314 +0,0 @@
-#!/usr/bin/env node
-import { realpathSync } from 'node:fs';
-import { Command, CommanderError } from 'commander';
-import { fileURLToPath } from 'node:url';
-import { runFactsGet } from './commands/facts.js';
-import { runFilingsGet, runFilingsList } from './commands/filings.js';
-import { parseResearchProfile, runResearchAsk, runResearchAskById, runResearchSync } from './commands/research.js';
-import { runResolve } from './commands/resolve.js';
-import { buildRuntimeOptions, parseDateString, parseNonNegativeInt, parsePositiveInt, requireUserAgent } from './core/config.js';
-import { failureEnvelope, successEnvelope } from './core/envelope.js';
-import { CLIError, ErrorCode, EXIT_CODE_MAP, isCLIError } from './core/errors.js';
-import { shapeData } from './core/output-shape.js';
-import { SecClient } from './sec/client.js';
-class CLIAbortError extends Error {
-    exitCode;
-    constructor(exitCode) {
-        super(`CLI exited with code ${exitCode}`);
-        this.exitCode = exitCode;
-        this.name = 'CLIAbortError';
-    }
-}
-function defaultIo() {
-    return {
-        stdout: (message) => process.stdout.write(message),
-        stderr: (message) => process.stderr.write(message),
-        env: process.env
-    };
-}
-function humanPrint(io, data) {
-    io.stdout(`${JSON.stringify(data, null, 2)}\n`);
-}
-function emitSuccess(params) {
-    const { context, io, command, result } = params;
-    if (context.runtime.humanMode) {
-        humanPrint(io, result.data);
-        return;
-    }
-    const shaped = shapeData({
-        data: result.data,
-        fields: context.runtime.fields,
-        limit: context.runtime.limit
-    });
-    const metaUpdates = {
-        ...(result.metaUpdates ?? {}),
-        ...shaped.metaUpdates
-    };
-    const envelope = successEnvelope({
-        command,
-        data: shaped.data,
-        view: context.runtime.view,
-        metaUpdates
-    });
-    io.stdout(`${JSON.stringify(envelope)}\n`);
-}
-function emitError(params) {
-    const { command, err, runtimeView, humanMode, io } = params;
-    if (humanMode) {
-        io.stderr(`${err.code} ${err.message}\n`);
-        return err.exitCode;
-    }
-    const envelope = failureEnvelope({
-        command,
-        code: err.code,
-        message: err.message,
-        retriable: err.retriable,
-        view: runtimeView
-    });
-    io.stdout(`${JSON.stringify(envelope)}\n`);
-    return err.exitCode;
-}
-function toCliError(err) {
-    if (isCLIError(err)) {
-        return err;
-    }
-    return new CLIError(ErrorCode.INTERNAL_ERROR, err.message || 'Unexpected error');
-}
-async function executeCommand(command, commandObj, io, handler, options) {
-    const globalOptions = commandObj.optsWithGlobals();
-    const runtime = buildRuntimeOptions({
-        json: globalOptions.json,
-        human: globalOptions.human,
-        view: globalOptions.view,
-        fields: globalOptions.fields,
-        limit: globalOptions.limit,
-        verbose: globalOptions.verbose,
-        userAgent: globalOptions.userAgent
-    }, io.env);
-    try {
-        const requiresSecIdentity = options?.requiresSecIdentity ?? true;
-        const userAgent = requiresSecIdentity
-            ? requireUserAgent(runtime.userAgent)
-            : runtime.userAgent ?? 'edgar-cli local research';
-        const secClient = new SecClient({
-            userAgent,
-            verbose: runtime.verbose,
-            logger: (message) => io.stderr(`[debug] ${message}\n`)
-        });
-        const context = {
-            runtime,
-            secClient
-        };
-        const result = await handler(context);
-        emitSuccess({ command, result, context, io });
-    }
-    catch (error) {
-        const cliError = toCliError(error);
-        const exitCode = emitError({
-            command,
-            err: cliError,
-            runtimeView: runtime.view,
-            humanMode: runtime.humanMode,
-            io
-        });
-        throw new CLIAbortError(exitCode);
-    }
-}
-export function buildProgram(io) {
-    const program = new Command();
-    program
-        .name('edgar')
-        .description('Agent-friendly SEC EDGAR CLI')
-        .option('--json', 'Emit JSON envelope output (default)')
-        .option('--human', 'Emit human-readable output')
-        .option('--view <view>', 'Output view mode (summary|full)', 'summary')
-        .option('--fields <fields>', 'Select specific response fields in JSON mode')
-        .option('--limit <n>', 'Limit output rows in JSON mode')
-        .option('--verbose', 'Enable verbose debug logs')
-        .option('--user-agent <value>', 'SEC identity (required for network commands), e.g. "Name email@domain.com"')
-        .showHelpAfterError(true)
-        .exitOverride()
-        .addHelpText('after', '\nSEC identity is required for network commands.\nSet --user-agent or EDGAR_USER_AGENT.')
-        .configureOutput({
-        writeOut: (message) => io.stdout(message),
-        writeErr: (message) => io.stderr(message)
-    });
-    program
-        .command('resolve')
-        .description('Resolve ticker/CIK to canonical SEC identity fields')
-        .argument('<id>', 'Ticker (AAPL) or CIK (320193 / 0000320193)')
-        .action(async function actionResolve(id) {
-        await executeCommand('resolve', this, io, async (context) => runResolve(id, context));
-    });
-    const filings = program.command('filings').description('Query filing metadata and filing documents');
-    filings
-        .command('list')
-        .requiredOption('--id <id>', 'Ticker or CIK')
-        .option('--form <form>', 'SEC form type, e.g. 10-K')
-        .option('--from <yyyy-mm-dd>', 'Lower filing-date bound')
-        .option('--to <yyyy-mm-dd>', 'Upper filing-date bound')
-        .option('--query-limit <n>', 'Limit rows before envelope shaping')
-        .option('--offset <n>', 'Offset rows before query-limit slicing', '0')
-        .action(async function actionFilingsList(options) {
-        const from = options.from ? parseDateString(options.from, '--from') : undefined;
-        const to = options.to ? parseDateString(options.to, '--to') : undefined;
-        const queryLimit = options.queryLimit === undefined
-            ? undefined
-            : parsePositiveInt(options.queryLimit, '--query-limit');
-        const offset = parseNonNegativeInt(options.offset, '--offset');
-        await executeCommand('filings list', this, io, async (context) => runFilingsList({
-            id: options.id,
-            form: options.form,
-            from,
-            to,
-            queryLimit,
-            offset
-        }, context));
-    });
-    filings
-        .command('get')
-        .requiredOption('--id <id>', 'Ticker or CIK')
-        .requiredOption('--accession <accession>', 'Accession number: XXXXXXXXXX-XX-XXXXXX')
-        .option('--format <format>', 'url|html|text|markdown', 'url')
-        .action(async function actionFilingsGet(options) {
-        const format = options.format;
-        if (!['url', 'html', 'text', 'markdown'].includes(format)) {
-            throw new CLIAbortError(emitError({
-                command: 'filings get',
-                err: new CLIError(ErrorCode.VALIDATION_ERROR, '--format must be one of url|html|text|markdown'),
-                runtimeView: 'summary',
-                humanMode: false,
-                io
-            }));
-        }
-        await executeCommand('filings get', this, io, async (context) => runFilingsGet({
-            id: options.id,
-            accession: options.accession,
-            format: format
-        }, context));
-    });
-    const facts = program.command('facts').description('Query SEC company facts (XBRL)');
-    facts
-        .command('get')
-        .requiredOption('--id <id>', 'Ticker or CIK')
-        .option('--taxonomy <taxonomy>', 'us-gaap|dei')
-        .option('--concept <concept>', 'Concept name, e.g. Revenues')
-        .option('--unit <unit>', 'Unit key, e.g. USD')
-        .option('--latest', 'Return only latest point per unit')
-        .action(async function actionFactsGet(options) {
-        const taxonomyValue = options.taxonomy;
-        if (taxonomyValue && !['us-gaap', 'dei'].includes(taxonomyValue)) {
-            throw new CLIAbortError(emitError({
-                command: 'facts get',
-                err: new CLIError(ErrorCode.VALIDATION_ERROR, '--taxonomy must be us-gaap or dei'),
-                runtimeView: 'summary',
-                humanMode: false,
-                io
-            }));
-        }
-        await executeCommand('facts get', this, io, async (context) => runFactsGet({
-            id: options.id,
-            taxonomy: taxonomyValue,
-            concept: options.concept,
-            unit: options.unit,
-            latest: Boolean(options.latest)
-        }, context));
-    });
-    const research = program
-        .command('research')
-        .description('Run deterministic research workflows over explicit docs or cached filing profiles');
-    research
-        .command('sync')
-        .description('Cache a deterministic research corpus for a company/profile')
-        .requiredOption('--id <id>', 'Ticker or CIK')
-        .option('--profile <profile>', 'core|events|financials', 'core')
-        .option('--cache-dir <path>', 'Override cache directory')
-        .option('--refresh', 'Force refetch even when cached docs exist')
-        .action(async function actionResearchSync(options) {
-        const profile = parseResearchProfile(options.profile);
-        await executeCommand('research sync', this, io, async (context) => runResearchSync({
-            id: options.id,
-            profile,
-            cacheDir: options.cacheDir,
-            refresh: Boolean(options.refresh)
-        }, context), { requiresSecIdentity: true });
-    });
-    research
-        .command('ask')
-        .description('Query explicitly provided local docs, or a cached company profile corpus when --id is used')
-        .argument('<query>', 'Natural language query')
-        .option('--id <id>', 'Ticker or CIK for cached/profile-based research')
-        .option('--profile <profile>', 'core|events|financials (used with --id)', 'core')
-        .option('--cache-dir <path>', 'Override cache directory')
-        .option('--refresh', 'With --id, force refetch of filings before querying')
-        .option('--doc <path>', 'Path to a local document (repeatable)', collectValues, [])
-        .option('--manifest <path>', 'Path to JSON manifest: either ["doc1", ...] or {"docs": ["doc1", ...]}')
-        .option('--top-k <n>', 'Maximum number of chunks to return', '8')
-        .option('--chunk-lines <n>', 'Number of lines per retrieval chunk', '40')
-        .option('--chunk-overlap <n>', 'Line overlap between retrieval chunks', '10')
-        .action(async function actionResearchAsk(query, options) {
-        const topK = parsePositiveInt(options.topK, '--top-k');
-        const chunkLines = parsePositiveInt(options.chunkLines, '--chunk-lines');
-        const chunkOverlap = parseNonNegativeInt(options.chunkOverlap, '--chunk-overlap');
-        const requiresSecIdentity = Boolean(options.id);
-        const profile = parseResearchProfile(options.profile);
-        await executeCommand('research ask', this, io, async (context) => options.id
-            ? runResearchAskById({
-                id: options.id,
-                query,
-                profile,
-                cacheDir: options.cacheDir,
-                refresh: Boolean(options.refresh),
-                topK,
-                chunkLines,
-                chunkOverlap
-            }, context)
-            : runResearchAsk({
-                query,
-                docs: options.doc ?? [],
-                manifestPath: options.manifest,
-                topK,
-                chunkLines,
-                chunkOverlap
-            }, context), { requiresSecIdentity });
-    });
-    return program;
-}
-function collectValues(value, previous) {
-    return [...previous, value];
-}
-export async function runCli(argv, io = defaultIo()) {
-    const program = buildProgram(io);
-    try {
-        await program.parseAsync(argv, { from: 'user' });
-        return 0;
-    }
-    catch (error) {
-        if (error instanceof CLIAbortError) {
-            return error.exitCode;
-        }
-        if (error instanceof CommanderError) {
-            return error.exitCode;
-        }
-        const cliError = toCliError(error);
-        io.stderr(`${cliError.code} ${cliError.message}\n`);
-        return EXIT_CODE_MAP[cliError.code] ?? 10;
-    }
-}
-function isDirectExecution() {
-    const argvPath = process.argv[1];
-    if (!argvPath) {
-        return false;
-    }
-    try {
-        return realpathSync(argvPath) === realpathSync(fileURLToPath(import.meta.url));
-    }
-    catch {
-        return false;
-    }
-}
-if (isDirectExecution()) {
-    runCli(process.argv.slice(2)).then((exitCode) => {
-        process.exit(exitCode);
-    });
-}