Cover CLI help safety and card handle lookup

[naturedesk]

Summary

• add regression coverage that publish-card --help and raw publish-card --help short-circuit without touching network/signing paths
• add regression coverage that raw card @handle resolves the handle before querying the GraphQL agent card
• clarify CLI command catalog text for card, publish-card, and card-update, including that full-card JSON belongs in --data
• lazy-load node-pty in the harness wrapper so non-PTY CLI tests/imports do not fail when the native module is absent; the existing pipe fallback still handles unavailable PTY at runtime

Verification

• ./node_modules/.bin/vitest run tests/cli.test.ts
• ./node_modules/.bin/tsc --noEmit

Notes

Current origin/main already had the core behavior fixes for #216/#217; this PR locks them with tests and clears up the help surface. The hosted /a2a/@handle and /a2a/@handle/skill.md behavior from #216 still requires backend/docs-hosting work outside this checkout.

Refs #216
Refs #217

Summary by CodeRabbit

• New Features

  • Directory card commands now accept either an @handle or an agent ID.
  • Card lookups using an @handle automatically resolve to the corresponding agent ID.

• Improvements

  • Updated profile command guidance with clearer examples for skills, endpoints, and agent-card data.
  • Command-specific help now works without requiring signing or making network requests.

[vercel]

@naturedesk is attempting to deploy a commit to the Vezures Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

📝 Walkthrough

Walkthrough

CLI help metadata now documents updated profile flags and handle-based card lookup. Tests cover signer-independent help output and resolving @handle values before GraphQL requests. node-pty is loaded dynamically inside runPtyAgent.

Changes

CLI command behavior

Layer / File(s)	Summary
Command metadata and behavior coverage sdk/typescript/src/cli/commands.ts, sdk/typescript/tests/cli.test.ts	Profile card commands document updated options, directory card lookup accepts @handle, help execution avoids network calls, and handle lookup precedes the GraphQL request.
Lazy PTY module loading sdk/typescript/src/cli/harness-wrapper.ts	node-pty is imported dynamically inside runPtyAgent while preserving its existing error-handling path.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• tinyhumansai/tiny.place#205: Touches the adjacent harness wrapper and PTY implementation.
• tinyhumansai/tiny.place#218: Overlaps with CLI help short-circuiting and handle resolution behavior.

Poem

A bunny hops through flags anew,
With handles pointing agents through.
Help speaks without a network call,
PTY waits until it’s called.
“Thump!” says the rabbit—clean and bright!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main changes: safer CLI help handling and card handle resolution.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b6f60e2830

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Keep node-pty imports at module scope

For files under this SDK, sdk/typescript/AGENTS.md says, “Always use top-level imports. Never use dynamic import() inside functions.” This new function-scoped import runs on the normal PTY launch path for tinyplace codex/claude, so it violates the repository’s required import discipline; please keep node-pty loading at module scope or refactor the fallback without adding an in-function dynamic import.

Useful? React with 👍 / 👎.

[coderabbitai]

🧹 Nitpick comments (1)

sdk/typescript/src/cli/harness-wrapper.ts (1)

266-266: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Dynamic import() inside a function violates coding guidelines.

The guideline for **/*.{js,jsx,ts,tsx} states: "Always use top-level imports. Never use dynamic import() inside functions." While the PR objective intentionally lazy-loads node-pty and tui.ts already uses the same pattern, this is still a guideline violation.

An alternative that satisfies both the lazy-loading requirement and the guideline: use the existing requireForHarness (from createRequire at line 55) instead of dynamic import(). The guideline prohibits dynamic import() specifically, not require():

♻️ Suggested refactor using existing `createRequire`

   try {
     fixNodePtyHelperPermissions();
-    const { spawn: spawnPty } = await import("node-pty");
+    const { spawn: spawnPty } = requireForHarness("node-pty") as typeof import("node-pty");
     pty = spawnPty(launch.command, launch.args, {

This keeps the load lazy (only triggered when runPtyAgent is called), avoids dynamic import(), and reuses infrastructure already in the file. If the team considers this an accepted exception (given the tui.ts precedent), please document it.

As per coding guidelines: **/*.{js,jsx,ts,tsx}: Always use top-level imports. Never use dynamic import() inside functions.

🤖 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 `@sdk/typescript/src/cli/harness-wrapper.ts` at line 266, Replace the dynamic
import inside runPtyAgent with the existing requireForHarness loader, while
preserving lazy loading of node-pty and the existing spawnPty alias. Reuse the
file’s createRequire-based infrastructure rather than adding a new loader or
top-level import.

Source: Coding guidelines

🤖 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.

Nitpick comments:
In `@sdk/typescript/src/cli/harness-wrapper.ts`:
- Line 266: Replace the dynamic import inside runPtyAgent with the existing
requireForHarness loader, while preserving lazy loading of node-pty and the
existing spawnPty alias. Reuse the file’s createRequire-based infrastructure
rather than adding a new loader or top-level import.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 31ac3e68-d42a-45f9-85b0-e24458d977cc

📥 Commits

Reviewing files that changed from the base of the PR and between adedeb7 and b6f60e2.

📒 Files selected for processing (3)

• sdk/typescript/src/cli/commands.ts
• sdk/typescript/src/cli/harness-wrapper.ts
• sdk/typescript/tests/cli.test.ts