fix: resolve npm version publishing and auth token discovery issues (#21)

* fix: resolve npm version publishing and auth token discovery issues

Fix .npmrc path resolution for bun publish --cwd by writing to ~/.npmrc instead of project root, ensuring token is discoverable regardless of working directory. Add plugin_version and repterm_api_version workflow inputs to enable manual version management for plugin-api and plugin-kubectl packages. Improve semantic-release workspace protocol handling to process all package.json files consistently.

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

* fix: add missing fumadocs-core dependency to docs app

The docs app imports from fumadocs-core/source but only had fumadocs-ui
and fumadocs-mdx as direct dependencies, causing webpack module
resolution failure in CI.

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

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: cnbailian

.github/workflows/build.yml

@@ -15,11 +15,19 @@ on:
         required: true
         type: boolean
         default: false
+      plugin_version:
+        description: "Plugin version to publish (e.g. 0.2.0)"
+        required: false
+        type: string
       release_repterm_api:
         description: "Release repterm-api"
         required: true
         type: boolean
         default: false
+      repterm_api_version:
+        description: "repterm-api version to publish (e.g. 0.2.0)"
+        required: false
+        type: string
 
 permissions:
   contents: write
@@ -115,7 +123,10 @@ jobs:
       - name: Resolve workspace protocol for npm compatibility
         run: |
           API_VERSION=$(jq -r .version packages/plugin-api/package.json)
-          sed -i "s/\"workspace:\*\"/\"^${API_VERSION}\"/g" packages/repterm/package.json
+          # Replace workspace:* in all package.json files (npm cannot parse bun's workspace protocol)
+          find packages -name package.json -not -path "*/node_modules/*" -exec sed -i "s/\"workspace:\*\"/\"^${API_VERSION}\"/g" {} +
+          # Remove workspaces field from root package.json so npm doesn't try to process the workspace graph
+          jq 'del(.workspaces)' package.json > package.json.tmp && mv package.json.tmp package.json
 
       - name: Setup Node.js
         uses: actions/setup-node@v4
@@ -232,10 +243,14 @@ jobs:
         run: bun install --frozen-lockfile
 
       - name: Configure npm auth
-        run: echo "//registry.npmjs.org/:_authToken=$NPM_TOKEN" > .npmrc
+        run: echo "//registry.npmjs.org/:_authToken=$NPM_TOKEN" > ~/.npmrc
         env:
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
 
+      - name: Set plugin version
+        if: inputs.plugin_version != ''
+        run: cd packages/plugin-kubectl && npm version ${{ inputs.plugin_version }} --no-git-tag-version
+
       - name: Build repterm-api package
         run: bun run build:plugin-api
 
@@ -263,10 +278,14 @@ jobs:
         run: bun install --frozen-lockfile
 
       - name: Configure npm auth
-        run: echo "//registry.npmjs.org/:_authToken=$NPM_TOKEN" > .npmrc
+        run: echo "//registry.npmjs.org/:_authToken=$NPM_TOKEN" > ~/.npmrc
         env:
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
 
+      - name: Set repterm-api version
+        if: inputs.repterm_api_version != ''
+        run: cd packages/plugin-api && npm version ${{ inputs.repterm_api_version }} --no-git-tag-version
+
       - name: Build repterm-api package
         run: bun run build:plugin-api
 

apps/docs/.gitignore

@@ -0,0 +1,6 @@
+# Fumadocs auto-generated
+.source/
+
+# Next.js
+.next/
+out/

apps/docs/app/docs/[[...slug]]/page.tsx

@@ -0,0 +1,46 @@
+import { source } from '@/lib/source';
+import {
+  DocsPage,
+  DocsBody,
+  DocsDescription,
+  DocsTitle,
+} from 'fumadocs-ui/page';
+import { notFound } from 'next/navigation';
+import defaultMdxComponents from 'fumadocs-ui/mdx';
+
+export default async function Page(props: {
+  params: Promise<{ slug?: string[] }>;
+}) {
+  const params = await props.params;
+  const page = source.getPage(params.slug);
+  if (!page) notFound();
+
+  const MDX = page.data.body;
+
+  return (
+    <DocsPage toc={page.data.toc} full={page.data.full}>
+      <DocsTitle>{page.data.title}</DocsTitle>
+      <DocsDescription>{page.data.description}</DocsDescription>
+      <DocsBody>
+        <MDX components={{ ...defaultMdxComponents }} />
+      </DocsBody>
+    </DocsPage>
+  );
+}
+
+export async function generateStaticParams() {
+  return source.generateParams();
+}
+
+export async function generateMetadata(props: {
+  params: Promise<{ slug?: string[] }>;
+}) {
+  const params = await props.params;
+  const page = source.getPage(params.slug);
+  if (!page) notFound();
+
+  return {
+    title: page.data.title,
+    description: page.data.description,
+  };
+}

apps/docs/app/docs/layout.tsx

@@ -0,0 +1,12 @@
+import { source } from '@/lib/source';
+import { DocsLayout } from 'fumadocs-ui/layouts/docs';
+import type { ReactNode } from 'react';
+import { baseOptions } from '@/app/layout.config';
+
+export default function Layout({ children }: { children: ReactNode }) {
+  return (
+    <DocsLayout tree={source.pageTree} {...baseOptions}>
+      {children}
+    </DocsLayout>
+  );
+}

apps/docs/app/global.css

@@ -0,0 +1,3 @@
+@import 'tailwindcss';
+@import 'fumadocs-ui/css/neutral.css';
+@import 'fumadocs-ui/css/preset.css';

apps/docs/app/layout.config.tsx

@@ -0,0 +1,14 @@
+import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
+
+export const baseOptions: BaseLayoutProps = {
+  nav: {
+    title: 'Repterm',
+  },
+  links: [
+    {
+      text: 'Documentation',
+      url: '/docs',
+      active: 'nested-url',
+    },
+  ],
+};

apps/docs/app/layout.tsx

@@ -0,0 +1,13 @@
+import { RootProvider } from 'fumadocs-ui/provider';
+import type { ReactNode } from 'react';
+import './global.css';
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body>
+        <RootProvider>{children}</RootProvider>
+      </body>
+    </html>
+  );
+}

apps/docs/app/page.tsx

@@ -0,0 +1,5 @@
+import { redirect } from 'next/navigation';
+
+export default function HomePage() {
+  redirect('/docs');
+}

apps/docs/content/docs/api/assertions.mdx

@@ -0,0 +1,59 @@
+---
+title: Assertions
+description: Reference for all built-in assertion matchers.
+---
+
+## CommandResult Assertions
+
+Use `expect(result)` where `result` is a `CommandResult` from `$` or `terminal.run()`.
+
+```ts
+const result = await $`echo hello`;
+
+// Success/failure
+await expect(result).toSucceed();           // code === 0
+await expect(result).toFail();              // code !== 0
+await expect(result).toHaveExitCode(0);     // specific exit code
+
+// Output matching
+await expect(result).toContainInOutput('hello');     // check combined output
+await expect(result).toHaveStdout('hello');          // partial stdout match
+await expect(result).toHaveStderr('error');          // partial stderr match
+
+// Regex matching
+await expect(result).toMatchStdout(/ready/i);        // regex on stdout
+await expect(result).toMatchStderr(/error/i);        // regex on stderr
+```
+
+### Assertion Reference
+
+| Matcher | Description |
+| --- | --- |
+| `toSucceed()` | Assert exit code is 0 |
+| `toFail()` | Assert exit code is non-zero |
+| `toHaveExitCode(code)` | Assert specific exit code |
+| `toContainInOutput(text)` | Assert combined stdout+stderr contains text |
+| `toHaveStdout(text)` | Assert stdout contains text |
+| `toHaveStderr(text)` | Assert stderr contains text |
+| `toMatchStdout(regex)` | Assert stdout matches regex pattern |
+| `toMatchStderr(regex)` | Assert stderr matches regex pattern |
+
+## Terminal Assertions
+
+Use `expect(terminal)` to assert on the current terminal state:
+
+```ts
+await expect(terminal).toContainText('prompt');    // text in terminal
+await expect(terminal).toMatchPattern(/\$\s/);     // regex on terminal
+```
+
+| Matcher | Description |
+| --- | --- |
+| `toContainText(text)` | Assert terminal output contains text |
+| `toMatchPattern(regex)` | Assert terminal output matches regex pattern |
+
+## Tips
+
+- In **Spawn mode**, exit code assertions (`toSucceed`, `toFail`, `toHaveExitCode`) work reliably.
+- In **PTY/Recording mode**, exit code is often `-1`. Prefer output assertions (`toContainInOutput`, `toHaveStdout`).
+- Use `$({ silent: true })` to get reliable exit codes in any mode.

apps/docs/content/docs/api/command-options.mdx

@@ -0,0 +1,134 @@
+---
+title: Command Options
+description: Full reference for RunOptions — configure timeout, environment, prompt detection, and more.
+---
+
+## RunOptions
+
+All command execution methods (`$`, `terminal.run()`) accept an options object:
+
+```ts
+interface RunOptions {
+  timeout?: number;
+  env?: Record<string, string>;
+  cwd?: string;
+  interactive?: boolean;
+  silent?: boolean;
+  typingSpeed?: number;
+  pauseAfter?: number;
+  pauseBefore?: number;
+  promptDetection?: 'auto' | 'osc133' | 'sentinel' | 'regex' | 'none';
+}
+```
+
+## Option Reference
+
+### timeout
+
+Command timeout in milliseconds. If the command doesn't complete within this time, it is killed.
+
+- **Default**: `300000` (5 minutes)
+- **Example**: `$({ timeout: 60_000 })\`long-running-cmd\``
+
+### env
+
+Additional environment variables for the command. Merged with the current environment.
+
+```ts
+await $({ env: { NODE_ENV: 'test', DEBUG: '1' } })`node app.js`;
+```
+
+### cwd
+
+Working directory for the command.
+
+```ts
+await $({ cwd: '/tmp/my-project' })`npm test`;
+```
+
+### interactive
+
+Enable PTY mode with `expect`/`send` control for interactive commands.
+
+- **Default**: `false`
+- **Example**: `$({ interactive: true })\`python3\``
+
+When enabled, the returned `PTYProcess` provides `expect()`, `send()`, `sendRaw()`, `interrupt()`, and `wait()` methods.
+
+### silent
+
+Force `Bun.spawn` even in PTY or recording mode. Use this when you need:
+- Reliable exit codes
+- Clean JSON output (no terminal escape sequences)
+- Separate stdout/stderr streams
+
+- **Default**: `false`
+- **Example**: `$({ silent: true })\`kubectl get pod -o json\``
+
+### typingSpeed
+
+Controls character typing speed during recording mode. Each character is typed with this delay between keystrokes.
+
+- **Default**: `80` (ms per character)
+- **`0`**: Instant typing (no animation)
+- **Example**: `$({ typingSpeed: 40 })\`echo "fast typing"\``
+
+Only affects recording mode. Ignored in other modes.
+
+### pauseAfter
+
+Pause after the command completes during recording mode. Useful for letting the viewer see the output before the next command.
+
+- **Default**: none
+- **Example**: `$({ pauseAfter: 2000 })\`echo "wait for it..."\``
+
+Only affects recording mode.
+
+### pauseBefore
+
+Pause before the command starts during recording mode.
+
+- **Default**: none
+- **Example**: `$({ pauseBefore: 1000 })\`echo "dramatic pause"\``
+
+Only affects recording mode.
+
+### promptDetection
+
+Override prompt detection strategy for this command.
+
+| Value | Description |
+| --- | --- |
+| `'auto'` | Best available method (default) |
+| `'osc133'` | Force OSC 133 detection only |
+| `'sentinel'` | Force sentinel marker detection |
+| `'regex'` | Force regex-based detection |
+| `'none'` | Skip prompt detection entirely |
+
+Use `'none'` for long-running or streaming commands where prompt detection is not applicable:
+
+```ts
+await $({ promptDetection: 'none' })`tail -f /var/log/syslog`;
+```
+
+## Usage Examples
+
+```ts
+// Simple command with timeout
+await $({ timeout: 5000 })`echo hello`;
+
+// Silent mode for reliable JSON parsing
+const result = await $({ silent: true })`kubectl get pods -o json`;
+const pods = JSON.parse(result.stdout);
+
+// Interactive command
+const proc = $({ interactive: true, timeout: 30_000 })`python3`;
+await proc.expect('>>>');
+await proc.send('exit()\n');
+
+// Recording with typing animation
+await $({ typingSpeed: 40, pauseAfter: 1000 })`ls -la`;
+
+// Custom environment and working directory
+await $({ env: { PORT: '3000' }, cwd: '/app' })`npm start`;
+```