alpic 0.0.0-staging.fc83d5f → 0.0.0-staging.fd696be

package/README.md

@@ -4,24 +4,6 @@ Deploy and manage your MCP servers from the command line.
 
 Full documentation: **https://docs.alpic.ai/cli/overview**
 
-## Install
-
-```bash
-npm install -g alpic
-```
-
-## Authenticate
-
-```bash
-alpic login
-```
-
-Or set an API key:
-
-```bash
-export ALPIC_API_KEY=your_api_key_here
-```
-
 ## Commands
 
 | Command | Description |
@@ -38,3 +20,53 @@ export ALPIC_API_KEY=your_api_key_here
 | `telemetry enable\|disable\|status` | Manage usage reporting |
 | `tunnel` | Expose local server to the internet |
 | `whoami` | Display current user |
+
+## Development
+
+Run `pnpm update:docs` to ensure CLI documentation stays aligned with the current CLI code before finalizing changes.
+
+For release validation, the safest way to test the current published versions is:
+
+```bash
+npx alpic@latest <command>
+npx alpic@staging <command>
+```
+
+`alpic@staging` is available for staging builds. For local development of this repository, execute `./bin/dev.js` instead of invoking a published package.
+
+### Testing locally
+
+**node-pty**: The root `postinstall` script automatically runs `chmod +x` on node-pty's `spawn-helper` binary (workaround for [microsoft/node-pty#850](https://github.com/microsoft/node-pty/issues/850)). No manual step needed, but if the `tunnel` command fails with a permission error, re-run `pnpm install`.
+
+**wellknown controller**: `alpic login` relies on OAuth discovery. The marketplace backend must be running locally and serving `http://localhost:3000/.well-known/oauth-protected-resource`. Without it, the login flow will fail.
+
+**Token management**: `alpic login` and `alpic logout` modify your stored credentials on disk. Check your current state with `alpic whoami` before and after tests to avoid accidentally clobbering your credentials.
+
+```bash
+# Point the CLI at the local API
+# Inline these env vars when running commands:
+# ALPIC_API_BASE_URL=http://localhost:3000 ALPIC_COGNITO_CLIENT_ID=2ab4khb8voo489m8qe2lj0u2lp
+alpic whoami
+alpic deploy
+```
+
+### Testing on staging
+
+```bash
+# Point the CLI at the staging API
+# Inline these env vars when running commands:
+# ALPIC_API_BASE_URL=https://api.staging.alpic.ai ALPIC_COGNITO_CLIENT_ID=2ab4khb8voo489m8qe2lj0u2lp
+alpic login   # uses staging credentials — separate from production
+alpic whoami
+alpic deploy
+```
+
+## Development Guidelines
+
+**Tests**: The CLI is heavily tested. Any change should be covered by the existing test suite, or you should add or extend tests so behavior stays protected.
+
+**Agent-first**: The CLI must work in non-TTY environments (Claude, Cursor, CI, etc.). Never call `p.spinner()` from `@clack/prompts` directly — use `createSpinner()` from `src/lib/agent-mode.ts`, which auto-detects agent mode via `@vercel/detect-agent` and falls back to plain `console.log`.
+
+**Exit handling**: Never call `process.exit()` directly from commands. Use one of the exit helpers provided by the Alpic base command so cleanup, formatting, and agent-mode behavior remain consistent.
+
+**`@clack/prompts` is for commands only**: Only command files (`src/commands/**`) and base command classes (`src/lib/alpic-command.ts`, `src/lib/base-workflow.ts`) may import `@clack/prompts` or write to the console. Library utilities in `src/lib/**` must return data — let the calling command handle output.

package/dist/__tests__/alpic-command.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/alpic-command.test.js

@@ -0,0 +1,41 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+const mockIsAuthenticated = vi.fn();
+const mockOauthLogin = vi.fn();
+vi.mock("../lib/auth/auth.js", () => ({
+    isAuthenticated: () => mockIsAuthenticated(),
+    oauthLogin: () => mockOauthLogin(),
+}));
+// Must import after vi.mock so the mock is in place
+const { AlpicCommand } = await import("../lib/alpic-command.js");
+class TestCommand extends AlpicCommand {
+    static id = "test";
+    async run() {
+        await this.ensureAuthenticated({ "non-interactive": false });
+    }
+}
+describe("ensureAuthenticated", () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    it("does nothing when already authenticated", async () => {
+        mockIsAuthenticated.mockResolvedValue(true);
+        const command = new TestCommand([], {});
+        await command.ensureAuthenticated({ "non-interactive": false });
+        expect(mockIsAuthenticated).toHaveBeenCalled();
+        expect(mockOauthLogin).not.toHaveBeenCalled();
+    });
+    it("triggers login flow when not authenticated in interactive mode", async () => {
+        mockIsAuthenticated.mockResolvedValue(false);
+        mockOauthLogin.mockResolvedValue(undefined);
+        const command = new TestCommand([], {});
+        await command.ensureAuthenticated({ "non-interactive": false });
+        expect(mockOauthLogin).toHaveBeenCalled();
+    });
+    it("exits with error when not authenticated in non-interactive mode", async () => {
+        mockIsAuthenticated.mockResolvedValue(false);
+        const command = new TestCommand([], {});
+        await expect(command.ensureAuthenticated({ "non-interactive": true })).rejects.toThrow();
+        expect(mockOauthLogin).not.toHaveBeenCalled();
+    });
+});
+//# sourceMappingURL=alpic-command.test.js.map

package/dist/__tests__/alpic-command.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alpic-command.test.js","sourceRoot":"","sources":["../../src/__tests__/alpic-command.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAE9D,MAAM,mBAAmB,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;AACpC,MAAM,cAAc,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;AAE/B,EAAE,CAAC,IAAI,CAAC,qBAAqB,EAAE,GAAG,EAAE,CAAC,CAAC;IACpC,eAAe,EAAE,GAAG,EAAE,CAAC,mBAAmB,EAAE;IAC5C,UAAU,EAAE,GAAG,EAAE,CAAC,cAAc,EAAE;CACnC,CAAC,CAAC,CAAC;AAEJ,oDAAoD;AACpD,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,yBAAyB,CAAC,CAAC;AAEjE,MAAM,WAAY,SAAQ,YAAY;IACpC,MAAM,CAAU,EAAE,GAAG,MAAM,CAAC;IAC5B,KAAK,CAAC,GAAG;QACP,MAAM,IAAI,CAAC,mBAAmB,CAAC,EAAE,iBAAiB,EAAE,KAAK,EAAE,CAAC,CAAC;IAC/D,CAAC;;AAGH,QAAQ,CAAC,qBAAqB,EAAE,GAAG,EAAE;IACnC,UAAU,CAAC,GAAG,EAAE;QACd,EAAE,CAAC,aAAa,EAAE,CAAC;IACrB,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yCAAyC,EAAE,KAAK,IAAI,EAAE;QACvD,mBAAmB,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;QAE5C,MAAM,OAAO,GAAG,IAAI,WAAW,CAAC,EAAE,EAAE,EAAW,CAAC,CAAC;QACjD,MAAM,OAAO,CAAC,mBAAmB,CAAC,EAAE,iBAAiB,EAAE,KAAK,EAAE,CAAC,CAAC;QAEhE,MAAM,CAAC,mBAAmB,CAAC,CAAC,gBAAgB,EAAE,CAAC;QAC/C,MAAM,CAAC,cAAc,CAAC,CAAC,GAAG,CAAC,gBAAgB,EAAE,CAAC;IAChD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gEAAgE,EAAE,KAAK,IAAI,EAAE;QAC9E,mBAAmB,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC;QAC7C,cAAc,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC;QAE5C,MAAM,OAAO,GAAG,IAAI,WAAW,CAAC,EAAE,EAAE,EAAW,CAAC,CAAC;QACjD,MAAM,OAAO,CAAC,mBAAmB,CAAC,EAAE,iBAAiB,EAAE,KAAK,EAAE,CAAC,CAAC;QAEhE,MAAM,CAAC,cAAc,CAAC,CAAC,gBAAgB,EAAE,CAAC;IAC5C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iEAAiE,EAAE,KAAK,IAAI,EAAE;QAC/E,mBAAmB,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC;QAE7C,MAAM,OAAO,GAAG,IAAI,WAAW,CAAC,EAAE,EAAE,EAAW,CAAC,CAAC;QAEjD,MAAM,MAAM,CAAC,OAAO,CAAC,mBAAmB,CAAC,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;QAEzF,MAAM,CAAC,cAAc,CAAC,CAAC,GAAG,CAAC,gBAAgB,EAAE,CAAC;IAChD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/__tests__/audit.e2e.test.d.ts

@@ -0,0 +1 @@
+export {};