@artblocks/abx-cli 0.1.0-alpha.3 → 0.1.0-alpha.30

package/dist/output.d.ts

@@ -0,0 +1,179 @@
+import { SelfHostIndexer } from '@artblocks/abx-indexer';
+import { type Address, type ProjectState, type PublicClient, type SendTx } from '@artblocks/abx-sdk';
+import { type Flags } from './flags.js';
+export declare const c: {
+    reset: string;
+    dim: string;
+    bold: string;
+    green: string;
+    purple: string;
+    orange: string;
+    red: string;
+};
+export declare const g: (s: string) => string;
+export declare const p: (s: string) => string;
+export declare const dim: (s: string) => string;
+export declare const bold: (s: string) => string;
+export declare let stepN: number;
+export declare const step: (s: string) => void;
+export declare const ok: (s: string) => void;
+export declare const info: (s: string) => void;
+export declare const warn: (s: string) => void;
+export declare function allowLargeScan(flags: Flags): void;
+/**
+ * Resolve the scan floor (fromBlock) for an add/index — the CLI-side shell around the SDK's
+ * {@link sdkResolveScanFloor}: builds the client, forwards `--from-block`, and narrates its two
+ * possible events (the SDK never prints). See the SDK function's doc comment for the "why" (never
+ * a silent genesis default).
+ */
+export declare function resolveScanFloor(address: Address, localFromBlock: string | undefined, flags: Flags): Promise<string>;
+/**
+ * The trust-anchor gate: a factory is THE address platforms allowlist by, so a missing
+ * manifest entry must NEVER silently mint a new "canonical" — that fragments trust (and
+ * a stale SDK would duplicate factories on real chains). Degrade to guidance; deploying
+ * a private trust anchor is an explicit choice (`--bootstrap-factory`).
+ */
+export declare function refuseMissingFactory(kind: string, envVar: string, reason: string): never;
+/** A `SendTx` that defers `makeWalletClient`/`makeHotSender` construction until the first actual
+ *  send — trust-anchor bootstrap is rare (an existing, current anchor is the common case), so the
+ *  happy path must never require a signing key. Memoized so a multi-tx bootstrap (the SeriesCode
+ *  factory: 2 libraries + the linked factory itself) reuses ONE sender — and its nonce tracking —
+ *  rather than a fresh one per send. */
+export declare function lazyBootstrapSender(publicClient: PublicClient): SendTx;
+/** Get (or deploy) the chain's canonical 1/1 clone factory — narrates the SDK's `ensureFactory`
+ *  (anchors.ts), which owns the resolve/verify/bootstrap logic; this keeps only the exact console
+ *  output plus the exit-messaging refusal (`refuseMissingFactory`), which stays CLI-side since the
+ *  SDK doesn't know a UX's flag names. `quiet` suppresses only the happy-path reuse line (the demo
+ *  resolves the factory without making a teaching moment of it) — everything else always prints. */
+export declare function ensureFactory(override?: string, allowBootstrap?: boolean, quiet?: boolean): Promise<Address>;
+/** Get (or deploy) the chain's `SeriesImageFactory` — the sibling of {@link ensureFactory}.
+ *  Narrates the SDK's `ensureSeriesFactory` (anchors.ts), which owns the resolve/verify/bootstrap
+ *  logic. */
+export declare function ensureSeriesFactory(override?: string, allowBootstrap?: boolean): Promise<Address>;
+/** Get (or deploy) the chain's shared `AbxMetadataRenderer` — narrates the SDK's `ensureRenderer`
+ *  (anchors.ts), which also self-heals to the CREATE2-deterministic address before deploying. No
+ *  `allowBootstrap` gate here (unlike the three clone factories) — the renderer isn't a platform
+ *  allowlist entry, so there's nothing to refuse; a stale/missing one always just gets redeployed. */
+export declare function ensureRenderer(override?: string): Promise<Address>;
+/** The code-project trust anchor — narrates the SDK's `ensureSeriesCodeFactory` (anchors.ts),
+ *  which owns the resolve/bootstrap logic (a sandbox / fresh chain links + deploys the two
+ *  write-path libraries then the factory in-flight; see {@link deploySeriesCodeFactory}). */
+export declare function ensureSeriesCodeFactory(publicClient: PublicClient, override?: string, allowBootstrap?: boolean): Promise<Address>;
+/** Get (or deploy) the chain's canonical 1/1-edition clone factory — narrates the SDK's
+ *  `ensureOneOfOneEditionFactory` (anchors.ts), the edition twin of {@link ensureFactory}. */
+export declare function ensureOneOfOneEditionFactory(override?: string, allowBootstrap?: boolean): Promise<Address>;
+/** Get (or deploy) the chain's `EditionImageFactory` — narrates the SDK's `ensureEditionFactory`
+ *  (anchors.ts), the edition twin of {@link ensureSeriesFactory}. */
+export declare function ensureEditionFactory(override?: string, allowBootstrap?: boolean): Promise<Address>;
+/** The code-project EDITION trust anchor — narrates the SDK's `ensureEditionCodeFactory`
+ *  (anchors.ts), the edition twin of {@link ensureSeriesCodeFactory} (three linked libraries
+ *  instead of two — see `deployEditionCodeFactory`'s doc note). */
+export declare function ensureEditionCodeFactory(publicClient: PublicClient, override?: string, allowBootstrap?: boolean): Promise<Address>;
+/** The canonical seed source — narrates the SDK's `ensureSeedSource` (anchors.ts): a clean keyless
+ *  singleton (like the renderer / chunk store / minter), so CREATE2 lands at THE canonical address
+ *  on any chain. Resolves from the manifest, self-heals to the predicted address (deployed but not
+ *  yet repointed), else auto-deploys via CREATE2. */
+export declare function ensureSeedSource(publicClient: PublicClient): Promise<Address>;
+/**
+ * Refuse a port that's already bound, with a formatted one-liner naming the port and the fix.
+ *
+ * Without this, `listen()` has no `'error'` handler and EADDRINUSE reaches Node's default handler:
+ * the creator gets a raw stack trace through `node:net` and our own `dist/` paths, which reads as a
+ * crash inside abx rather than "something else is on this port" — and it's the one unformatted error
+ * surface in a CLI where every other error is formatted. `preview`'s default port colliding with a
+ * studio left running in another terminal was reported as especially hard to diagnose.
+ */
+export declare function assertPortFree(port: number, cmd: string): Promise<void>;
+/** Is a TCP port already bound on localhost? Used to preflight a serve BEFORE spending a tx. */
+export declare function portInUse(port: number): Promise<boolean>;
+/**
+ * Index a project we *just* deployed — and don't believe a zero.
+ *
+ * `eth_getLogs` is read-after-write inconsistent on load-balanced RPCs: `waitForTransactionReceipt`
+ * resolves against a node that has the block, then the log query lands on one that doesn't yet, and
+ * returns an empty set for a block we KNOW contains our deploy. The old code took that single read at
+ * face value, printed `✓ reconstructed 0 events`, stored the empty projection, and served an empty
+ * dashboard — a first-run that looks like the toolkit simply doesn't work. It reproduced 100% of the
+ * time on `https://sepolia.base.org`, which is the DEFAULT endpoint when there's no `.env`, i.e. the
+ * documented first run was the broken path. The same block returned all 9 logs seconds later.
+ *
+ * We have the one thing that makes this checkable: we just minted, so the spine cannot be empty.
+ * So verify instead of trusting — re-scan at a constant delay until events appear, and if they
+ * never do, say so as a FAILURE with the recovery command rather than dressing a zero up as a ✓.
+ */
+export declare function reindexAfterDeploy(indexer: SelfHostIndexer, address: Address, opts?: {
+    attempts?: number;
+    delayMs?: number;
+    readUriDocuments?: boolean;
+}): Promise<{
+    state: ProjectState;
+    elapsedMs: number;
+}>;
+export declare function loadEffects(): Promise<typeof import('@artblocks/abx-effects')>;
+/**
+ * The publish topology's one hard prerequisite, checked BEFORE any capture.
+ *
+ * A resolver that doesn't share this machine's disk serves referenced output (the still, a video, a
+ * model) by **redirect** — so it needs a URL, and it refuses the bytes (`specs/protocol/effects.md →
+ * Bound vs referenced`). A backend that can't name a locator therefore has no publish lane at all,
+ * and every render against one would be work spent to earn a 400.
+ *
+ * So this refuses up front and names the ways out, rather than warning and letting the render run.
+ * It deliberately does NOT pick a backend for the operator: which store holds their content — and which
+ * gateway serves it — is theirs to decide. The three that work are peers, not a ranking: `https://`
+ * from S3/R2, an IPFS gateway, and Arweave are all fine, because derived output is re-creatable and
+ * the only real requirement is that a third party can fetch it.
+ */
+export declare function requirePublishableBackend(flags: Flags, what: string): void;
+export declare function printServing(url: string, address?: Address): void;
+/**
+ * The CLI package's own root — the directory holding its `package.json`, found by walking up rather
+ * than by counting `..`.
+ *
+ * **Counting is the bug this exists to prevent, and it shipped.** `resolveBundledSkill` and
+ * `resolveRendererScaffold` each computed the root as `resolve(fileURLToPath(import.meta.url), '..',
+ * '..')`. That is right for a module compiled to `dist/main.js` and wrong for one compiled to
+ * `dist/commands/scaffold.js`, which is one level deeper — it lands on `dist/`, not the package root.
+ * Both functions live in `src/commands/`, so in every published install they looked for
+ * `<pkg>/dist/skill` and `<pkg>/dist/assets/renderer-scaffold`, neither of which exists. The result:
+ * `abx skill install` — the CANONICAL way a user installs the agent skill, the first thing our own
+ * quickstart tells them to run — failed on every fresh npm install with "bundled skill not found",
+ * and `abx scaffold-renderer` failed the same way. Reported from the field on v0.1.0-alpha.21.
+ *
+ * Nothing caught it because dev runs from source (`pnpm abx`), where the fallback to the canonical
+ * repo copy makes both functions work regardless of the arithmetic. The published layout is the only
+ * place the number matters, and no test constructed one.
+ *
+ * So: no fixed depth anywhere. A file can move between `src/` and `src/commands/` without silently
+ * breaking a path, and `packaging.test.ts` fails the build if fixed-depth root math comes back.
+ */
+export declare function findCliPackageRoot(): string | null;
+/**
+ * The walk itself, as a pure function of a starting path — so it can be tested against a SIMULATED
+ * published layout, which is the one layout a dev run never has and therefore the one the original
+ * bug hid in. `findCliPackageRoot()` is this applied to the running module.
+ *
+ * @param from a file path inside the package (the walk starts at its directory)
+ * @param name the `package.json` `name` that identifies the root
+ */
+export declare function packageRootFrom(from: string, name?: string): string | null;
+/** Walk up from the CLI source to the workspace root (the dir with pnpm-workspace.yaml). Returns
+ *  null when running from a published install (no workspace) — where --from-source doesn't apply. */
+export declare function findRepoRoot(): string | null;
+export declare function keepAlive(): Promise<void>;
+/**
+ * Pick the canonical factory for a clone being added — the CLI-side shell around the SDK's
+ * {@link sdkDetectCanonicalFactory} (which does the actual multicall probe; see its doc comment).
+ * Shared by `add`'s local + remote paths (project.ts) and the deploy family's post-setup local
+ * register (deploy.ts, via {@link registerAndIndexLocally}).
+ */
+export declare function detectCanonicalFactory(address: Address, override?: string, stored?: string | null): Promise<Address | undefined>;
+/**
+ * Register + index a project LOCALLY (this node's own SQLite-backed projection) — the core of
+ * `abx add`'s non-`--remote` path, factored out here because it's ALSO how `deploy` / `deploy-series`
+ * / `deploy-code` register the project they just deployed (see cmdAdd in commands/project.ts, whose
+ * local branch is a thin call to this). Kept self-sufficient (recomputes any `--attributes`/`--traits`
+ * edit from `flags` itself) so it never depends on a caller's local variables.
+ */
+export declare function registerAndIndexLocally(address: Address, flags: Flags): Promise<void>;
+//# sourceMappingURL=output.d.ts.map

package/dist/output.d.ts.map

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