pinnace 0.0.0 → 0.2.0

package/dist/cli/run.d.ts

@@ -0,0 +1,94 @@
+import { type NodeVerb, type NodeCommandContext, type NodeCommandResult } from '../node/node-commands.js';
+import { type ListSitesInput, type SiteListing, type RemoveSiteInput, type RemoveSiteResult, type AddSiteInput, type AddSiteResult } from '../site/site-management.js';
+import { type PromoteReplicaInput, type PromoteReplicaResult } from '../publisher/record-sequence.js';
+import { type DeriveIpnsInput as DeriveIpnsKeyInput, type DerivedIpnsKey } from '../derive/ipns-key-derivation.js';
+import { type ProvisionInput, type ProvisionResult } from '../provision/cloud-init.js';
+import { type DeployInput, type DeployResult } from '../deploy/deploy.js';
+import { type EmitCiInput, type EmittedCi } from '../ci/ci-emit.js';
+import { type StatusReportInput, type StatusReport } from '../status/status-report.js';
+import { type DeriveIpnsInput } from '../derive/ipns-key-derivation.js';
+import { type PinnaceConfigFile, type EnvRecord } from '../config/config-resolution.js';
+/**
+ * The core functions the client verbs dispatch to. This seam is what makes the
+ * CLI a THIN wrapper AND independently testable: production wires the real core
+ * ({@link DEFAULT_DEPS}); tests inject recording stubs and assert each verb
+ * calls the RIGHT function with the correctly-resolved arguments (rather than
+ * re-testing the core through the CLI).
+ */
+export interface ClientDeps {
+    /** `provision` -> the cloud-init generator. */
+    provision(input: ProvisionInput): ProvisionResult;
+    /** `deploy` -> the multi-target CAR deploy. */
+    deploy(input: DeployInput): Promise<DeployResult>;
+    /** `install-ci` -> the CI workflow emitter. */
+    emitCi(input: EmitCiInput): EmittedCi;
+    /** `status` -> the per-site status report. */
+    statusReport(input: StatusReportInput): Promise<StatusReport>;
+    /** `derive` -> the master + site `id` -> IPNS id derivation (no deploy). */
+    deriveIpnsId(input: DeriveIpnsInput): string;
+    /** `node <verb>` -> the on-box command runner (context assembled by the CLI). */
+    runNodeCommand(verb: NodeVerb, ctx: NodeCommandContext): Promise<NodeCommandResult>;
+    /** `site list` -> enumerate the node's MFS sites. */
+    listSites(input: ListSitesInput): Promise<SiteListing[]>;
+    /** `site remove` -> drop an MFS site + unpin its content. */
+    removeSite(input: RemoveSiteInput): Promise<RemoveSiteResult>;
+    /** `site add` -> place an already-imported CID into MFS as a site. */
+    addSite(input: AddSiteInput): Promise<AddSiteResult>;
+    /** `promote` -> derive the per-site key material from the master + `id`. */
+    deriveIpnsKey(input: DeriveIpnsKeyInput): DerivedIpnsKey;
+    /** `promote` -> import the key + flip the node's role to publisher (story 14). */
+    promoteReplicaToPublisher(input: PromoteReplicaInput): Promise<PromoteReplicaResult>;
+}
+/**
+ * The CLI run context: the injectable env/config/output/core seams. Everything
+ * is optional; omitted fields default to the real process environment, a real
+ * `pinnace.json` read, `console` sinks, and the real core. Tests pass explicit
+ * in-memory values to stay hermetic.
+ */
+export interface RunContext {
+    /** The env layer (defaults to `process.env`). Tests pass an in-memory record. */
+    env?: EnvRecord;
+    /**
+     * Load the parsed config file (defaults to reading `./pinnace.json`, or an
+     * empty config if absent). Tests pass an in-memory object.
+     *
+     * `path` is the operator's explicit `--config <path>` when given, else
+     * `undefined` (the `./pinnace.json` default). The default loader treats an
+     * ABSENT default file as a benign empty config, but an explicitly-named path
+     * that is missing / unreadable / invalid JSON must THROW so `run()` can fail
+     * loud naming that path (an operator-named file is a claim it exists).
+     */
+    loadConfigFile?: (path?: string) => PinnaceConfigFile;
+    /** The core functions to dispatch to (defaults to the real core). */
+    deps?: ClientDeps;
+    /** stdout sink (defaults to `console.log`). */
+    out?: (line: string) => void;
+    /** stderr sink (defaults to `console.error`). */
+    err?: (line: string) => void;
+}
+/**
+ * An explicitly-named `--config <path>` could not be read or parsed. Names the
+ * path so `run()` can emit a loud, operator-actionable error (exit 1) instead
+ * of silently resolving to an empty config.
+ */
+export declare class ConfigLoadError extends Error {
+    readonly path: string;
+    readonly kind: 'read' | 'parse';
+    constructor(path: string, kind: 'read' | 'parse', cause?: unknown);
+}
+/**
+ * Dispatch a pinnace CLI invocation. Returns the process exit code.
+ *
+ * Routes the client verbs (provision/deploy/install-ci/status/derive), the
+ * on-box `node` namespace, and the `site` namespace. A missing command is a
+ * benign no-op (exit 0); an UNKNOWN command is loud (exit 1) so the surface is
+ * an explicit allow-list, not a silent catch-all.
+ *
+ * A GLOBAL `--config <path>` flag may appear BEFORE the command; it is consumed
+ * here (stripped from the per-verb argv) and threaded into config loading via
+ * the {@link RunContext.loadConfigFile} seam. With no `--config`, the default
+ * `./pinnace.json` is read and its absence is benign; an explicitly-named path
+ * that is missing/unreadable/invalid JSON fails loud (names the path, exit 1).
+ */
+export declare function run(argv: readonly string[], context?: RunContext): Promise<number>;
+//# sourceMappingURL=run.d.ts.map

package/dist/cli/run.d.ts.map

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