Skip to content

chore(cli): make CLI publishable as @zaks-io/agent-paste#142

Merged
isuttell merged 2 commits into
mainfrom
chore/publish-cli
May 29, 2026
Merged

chore(cli): make CLI publishable as @zaks-io/agent-paste#142
isuttell merged 2 commits into
mainfrom
chore/publish-cli

Conversation

@isuttell

@isuttell isuttell commented May 29, 2026

Copy link
Copy Markdown
Contributor

Summary

Makes the CLI publishable to npm as @zaks-io/agent-paste. The package was previously private (agent-paste@0.0.0) and built with plain tsc, leaving @agent-paste/* workspace deps as bare workspace:* imports that are uninstallable once published. This bundles those deps into a single self-contained dist/index.js.

The npm name was settled as @zaks-io/agent-paste (a reserved 0.0.0 placeholder already exists, maintainer isuttell); the unscoped agent-paste is blocked by a similarly-named package. The installed binary stays agent-paste.

Changes

  • Package metadata: rename to @zaks-io/agent-paste@0.1.0, drop private, add description/homepage/repository/files/publishConfig.access:public/prepublishOnly. Drop the dead exports field (nothing imports the CLI as a module).
  • Build: replace tsc with build.mjs (esbuild). Bundles src/index.ts + the @agent-paste/* workspace deps into one ESM file, resolving deps from TS source via the types export condition (no dep pre-compile needed). @napi-rs/keyring stays external (ships native .node binaries).
  • Deps: @agent-paste/* moved to devDependencies (bundled, not runtime); @napi-rs/keyring is the sole runtime dependency.
  • Paths: output dist/src/index.js -> dist/index.js; bin and the three smoke scripts updated to match.
  • References: all npx agent-paste -> npx @zaks-io/agent-paste across apex copy/llms/agents, web dashboard UI, and the brand guide (incl. the apex test assertions).
  • README: rewritten for public npm. Removed internal SDK/ADR rationale and repo-relative links (would 404 on npm and aren't shipped), fixed the stale not_authenticated error string, documented --artifact-id and AGENT_PASTE_API_URL.

Not in scope / follow-up

  • No license field, by design. The package stays UNLICENSED until the open-core licensing decision lands. It builds and packs correctly but is not yet meant to actually publishnpm publish is gated on that decision.
  • Version is 0.1.0 (placeholder burned 0.0.0).

Risk

LOW. Mechanical rename + bundler swap + doc/copy churn. No auth, secrets, or data-path logic touched; the keyring and credential code is unchanged.

Test plan

  • pnpm --filter @zaks-io/agent-paste build -> self-contained dist/index.js (verified no @agent-paste/* imports leak; one shebang; runs from a fully wiped dist tree)
  • pnpm --filter @zaks-io/agent-paste typecheck clean; CLI tests 40/40; apex tests 17/17; lint clean; knip clean
  • npm pack ships exactly dist/, README.md, package.json; isolated install of the tarball into a temp dir adds only @napi-rs/keyring (no @agent-paste/*), and the installed agent-paste binary runs (--help exit 0, whoami returns the proper not_authenticated error)
  • Local workflow-code-review: READY FOR PR, no blockers

🤖 Generated with Claude Code

Summary by CodeRabbit

  • New Features

    • CLI published as a scoped, public npm package (@zaks-io/agent-paste v0.1.0).
    • Requires Node.js 24+.
  • Documentation

    • All CLI examples and marketing copy updated to the new scoped package name.
    • README overhauled with clearer authentication (API key and interactive login), publish guidance (single-file and revisions), flags/JSON output, and improved error/usage notes.

Review Change Stack

@coderabbitai

coderabbitai Bot commented May 29, 2026

Copy link
Copy Markdown

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 6764c712-a215-4fd4-8402-284e8f110f43

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review
📝 Walkthrough

Walkthrough

This PR renames the CLI package from agent-paste to @zaks-io/agent-paste, adds an esbuild bundling step to produce dist/index.js, rewrites the CLI README with updated auth/command docs, and updates all marketing, web, test, and smoke-script references to the new scoped package and bundle path.

Changes

CLI Package Publishing and Documentation

Layer / File(s) Summary
CLI Package Publishing Infrastructure
apps/cli/package.json, apps/cli/build.mjs
Package identity changed to @zaks-io/agent-paste (v0.1.0) with public publish settings; new esbuild build.mjs bundles src/index.tsdist/index.js (ESM, node24). Runtime deps pared down and @napi-rs/keyring kept external.
CLI README Documentation
apps/cli/README.md
README rewritten: Node.js 24+ requirement, PKCE browser login flow, AGENT_PASTE_API_KEY precedence and behavior, Commands/Flags table updates, --json output semantics, error structure (code vs message), and publish/idempotency guidance.
Marketing, Web, and Documentation CLI References
apps/apex/src/agents.ts, apps/apex/src/copy.ts, apps/apex/src/llms.ts, apps/web/src/components/dashboard/FirstRunKeyCard.tsx, apps/web/src/routes/_authed.artifacts.index.tsx, apps/web/src/routes/_authed.dashboard.tsx, apps/web/src/routes/_authed.keys.tsx, docs/marketing-brand-guide.md, package.json
All user-visible CLI command strings updated from npx agent-paste to npx @zaks-io/agent-paste`` across marketing copy, web UI empty-states and headers, documentation examples, and root workspace npm script filters.
Test Assertions and Smoke Script Updates
apps/apex/src/index.test.ts, scripts/smoke-hosted.mjs, scripts/smoke-local-mvp.mjs, scripts/smoke-web-api.mjs
Apex tests now assert the scoped CLI strings; smoke test scripts and invocations updated to run the bundled CLI at apps/cli/dist/index.js instead of dist/src/index.js.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

  • zaks-io/agent-paste#76: Updates multiple UI/docs/test strings to use the same npx @zaks-io/agent-paste`` scoped package invocation pattern.
  • zaks-io/agent-paste#63: Edits similar Apex marketing/onboarding copy and CLI invocation changes from unscoped to scoped naming.
  • zaks-io/agent-paste#99: Overlaps on docs/marketing-brand-guide.md updates aligning CLI command wording with the scoped package.

Poem

🐇 Scoped and bundled, I hop with delight,
Docs polished by moon and by daylight,
Tests updated, scripts now align,
One command to run, one name to shine—
@zaks-io/agent-paste, oh so bright!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The pull request title clearly and accurately summarizes the main change: making the CLI package publishable to npm under the @zaks-io scope with updated versioning and metadata.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch chore/publish-cli

Comment @coderabbitai help to get the list of available commands and usage tips.

@isuttell

Copy link
Copy Markdown
Contributor Author

@coderabbitai full review

@coderabbitai

coderabbitai Bot commented May 29, 2026

Copy link
Copy Markdown
✅ Actions performed

Full review triggered.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@apps/cli/README.md`:
- Around line 139-141: The fenced code block showing the error "agent-paste:
not_authenticated: Set AGENT_PASTE_API_KEY or pass an auth provider." is missing
a language tag; update that fence to use a language (e.g., add "text" after the
opening backticks) so the block becomes ```text ... ``` to satisfy markdownlint
MD040 and improve rendering. Locate the exact block containing the error string
and add the language identifier to the opening fence.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 471b64fb-a8f7-49a9-b83d-96ecbbd8a669

📥 Commits

Reviewing files that changed from the base of the PR and between d317f8a and ca83c3d.

⛔ Files ignored due to path filters (1)
  • pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml
📒 Files selected for processing (16)
  • apps/apex/src/agents.ts
  • apps/apex/src/copy.ts
  • apps/apex/src/index.test.ts
  • apps/apex/src/llms.ts
  • apps/cli/README.md
  • apps/cli/build.mjs
  • apps/cli/package.json
  • apps/web/src/components/dashboard/FirstRunKeyCard.tsx
  • apps/web/src/routes/_authed.artifacts.index.tsx
  • apps/web/src/routes/_authed.dashboard.tsx
  • apps/web/src/routes/_authed.keys.tsx
  • docs/marketing-brand-guide.md
  • package.json
  • scripts/smoke-hosted.mjs
  • scripts/smoke-local-mvp.mjs
  • scripts/smoke-web-api.mjs

Comment thread apps/cli/README.md Outdated
@isuttell

Copy link
Copy Markdown
Contributor Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented May 29, 2026

Copy link
Copy Markdown
✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
apps/cli/README.md (1)

96-113: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

JSON example looks inconsistent with the human-readable output.

In the human output, View is a usercontent.agent-paste.sh/v/... URL while Agent View is api.agent-paste.sh/v1/artifacts/.../agent-view. In the JSON example, view_url and agent_view_url are identical (.../v1/public/agent-view/...), which both contradicts the human View URL and looks like a copy-paste. Please confirm the documented view_url matches the actual publish result shape.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/cli/README.md` around lines 96 - 113, The README's JSON example is
inconsistent with the human-readable output: update the JSON snippet so the
view_url key matches the human "View" URL (the usercontent.agent-paste.sh/v/...
style shown under "View") and the agent_view_url key matches the human "Agent
View" URL (the api.agent-paste.sh/v1/artifacts/<artifact_id>/agent-view style
shown under "Agent View"); edit the JSON example in apps/cli/README.md to
replace the duplicated "/v1/public/agent-view/..." values with the correct
view_url and agent_view_url values that reflect the actual publish result shape.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@apps/cli/README.md`:
- Around line 96-113: The README's JSON example is inconsistent with the
human-readable output: update the JSON snippet so the view_url key matches the
human "View" URL (the usercontent.agent-paste.sh/v/... style shown under "View")
and the agent_view_url key matches the human "Agent View" URL (the
api.agent-paste.sh/v1/artifacts/<artifact_id>/agent-view style shown under
"Agent View"); edit the JSON example in apps/cli/README.md to replace the
duplicated "/v1/public/agent-view/..." values with the correct view_url and
agent_view_url values that reflect the actual publish result shape.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 7bf72cd0-7b7b-4c30-8dbd-e0a8935a07cd

📥 Commits

Reviewing files that changed from the base of the PR and between ca83c3d and 2342262.

⛔ Files ignored due to path filters (1)
  • pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml
📒 Files selected for processing (16)
  • apps/apex/src/agents.ts
  • apps/apex/src/copy.ts
  • apps/apex/src/index.test.ts
  • apps/apex/src/llms.ts
  • apps/cli/README.md
  • apps/cli/build.mjs
  • apps/cli/package.json
  • apps/web/src/components/dashboard/FirstRunKeyCard.tsx
  • apps/web/src/routes/_authed.artifacts.index.tsx
  • apps/web/src/routes/_authed.dashboard.tsx
  • apps/web/src/routes/_authed.keys.tsx
  • docs/marketing-brand-guide.md
  • package.json
  • scripts/smoke-hosted.mjs
  • scripts/smoke-local-mvp.mjs
  • scripts/smoke-web-api.mjs
✅ Files skipped from review due to trivial changes (5)
  • apps/web/src/routes/_authed.dashboard.tsx
  • apps/web/src/components/dashboard/FirstRunKeyCard.tsx
  • package.json
  • docs/marketing-brand-guide.md
  • apps/apex/src/agents.ts
🚧 Files skipped from review as they are similar to previous changes (9)
  • apps/apex/src/llms.ts
  • apps/web/src/routes/_authed.artifacts.index.tsx
  • scripts/smoke-hosted.mjs
  • scripts/smoke-web-api.mjs
  • apps/apex/src/index.test.ts
  • apps/web/src/routes/_authed.keys.tsx
  • apps/cli/build.mjs
  • apps/apex/src/copy.ts
  • scripts/smoke-local-mvp.mjs

Rename apps/cli from private agent-paste@0.0.0 to public
@zaks-io/agent-paste@0.1.0 and switch the build from tsc to an esbuild
bundle so the published package has no workspace:* runtime deps.

- build.mjs bundles src/index.ts plus the @agent-paste/* workspace deps
  into a single ESM dist/index.js, resolving deps from TS source via the
  "types" export condition; @napi-rs/keyring stays external (native).
- Move @agent-paste/* to devDependencies; @napi-rs/keyring is the sole
  runtime dependency. Add files/repository/homepage/publishConfig and a
  prepublishOnly build guard. Drop the dead "exports" field.
- Output path dist/src/index.js -> dist/index.js; update bin and the
  three smoke scripts.
- Replace all "npx agent-paste" references with "npx @zaks-io/agent-paste"
  across apex copy/llms/agents, web dashboard UI, and the brand guide.
- Rewrite the CLI README for public npm: drop internal SDK/ADR rationale
  and repo-relative links, fix the not_authenticated error string, and
  document --artifact-id and AGENT_PASTE_API_URL.

No license field by design: the package stays UNLICENSED until the
open-core licensing decision lands, so it is not yet meant for publish.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@isuttell

Copy link
Copy Markdown
Contributor Author

Rebased onto main (resolved a package.json conflict from #141; dropped a dead agent-skills:check line that #141 had already removed).

Also: making the CLI public tripped the repo-lint monorepo-policy guardrail ("workspace packages must be private"). Added a narrow allowlist (publishablePackages = {@zaks-io/agent-paste}) in packages/repo-lint/src/monorepo-policy.mjs so only the CLI is exempt; every other package still must be private. This is the deliberate policy change that flips the repo's nothing-publishes stance for the one shippable artifact.

The pre-push hook ran only knip + test:coverage, and pre-commit typechecked
only changed packages. Neither ran `pnpm lint`, so repo-lint policy failures
(and anything else in `verify`) only surfaced in CI. Run `pnpm verify`
(lint, typecheck, test, knip, openapi:check, db:check, docs format) plus
test:coverage on pre-push so the local gate matches CI.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@isuttell isuttell merged commit 687e33c into main May 29, 2026
4 checks passed
@isuttell isuttell deleted the chore/publish-cli branch May 29, 2026 21:09
@github-actions

Copy link
Copy Markdown

agent-paste PR preview resources were cleaned up. The shared Preview GitHub Environment is retained for future preview deploys.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant