@vucinatim/agentic-devtools 0.1.0

package/docs/publishing.md

@@ -0,0 +1,211 @@
+# Publishing
+
+Agentic Devtools should publish to npm from GitHub Actions using npm Trusted
+Publishing.
+
+The package should be published primarily for `npx` MCP execution:
+
+```bash
+npx -y @vucinatim/agentic-devtools mcp railway
+```
+
+Library imports are supported, but they are not the main user onboarding path.
+
+## Recommended Flow
+
+Use:
+
+- GitHub public repo: `vucinatim/agentic-devtools`
+- npm package: `@vucinatim/agentic-devtools`
+- GitHub Actions CI
+- npm Trusted Publishing through OIDC
+- provenance attestations
+
+Do not use long-lived npm automation tokens unless Trusted Publishing is blocked.
+
+## Why Trusted Publishing
+
+npm Trusted Publishing creates a trust relationship between npm and the CI
+provider through OIDC. For GitHub Actions, the workflow needs `id-token: write`
+permission so npm can verify the workflow identity.
+
+npm also publishes provenance attestations automatically when Trusted Publishing
+is used from supported CI.
+
+References:
+
+- <https://docs.npmjs.com/trusted-publishers>
+- <https://docs.npmjs.com/generating-provenance-statements>
+- <https://docs.github.com/actions/automating-your-workflow-with-github-actions/publishing-nodejs-packages>
+
+## Release Management Recommendation
+
+Start simple.
+
+Phase 1:
+
+- manually bump `package.json` version in a PR
+- merge after CI passes
+- publish from a manual GitHub Actions workflow
+- create a GitHub release for the version tag
+
+This avoids heavy release machinery while the package API is still settling.
+
+Phase 2:
+
+- add Changesets once releases become frequent
+- require a changeset for user-visible package changes
+- let the release PR update version and changelog
+- publish after the release PR lands
+
+Changesets is a good fit later because it makes the changelog user-facing rather
+than deriving release notes only from commit messages.
+
+Reference:
+
+- <https://github.com/changesets/action>
+
+## Air Jam Reference
+
+Air Jam has a more advanced public package release system:
+
+- `release:public`
+- `release:public:next`
+- tag-triggered publishing
+- selected package publishing
+- release validation gates
+- GitHub release creation
+- `pnpm publish --provenance`
+
+That is a strong setup for a multi-package repo. Agentic Devtools should borrow
+the quality bar and provenance posture, not the full custom release machinery
+yet.
+
+For this repo, one package means a smaller workflow is cleaner.
+
+## Initial CI
+
+CI should run on pull requests and pushes to `main`:
+
+```yaml
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
+        with:
+          node-version: "24"
+          cache: "npm"
+      - run: npm ci
+      - run: npm run check
+```
+
+This repo currently uses npm because it is a single package. If it later moves
+to pnpm, mirror Air Jam's `corepack` pattern.
+
+## Initial Publish Workflow
+
+The first publish workflow should be manual:
+
+```yaml
+name: Publish
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "npm dist-tag"
+        required: true
+        default: "latest"
+        type: choice
+        options:
+          - latest
+          - next
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
+        with:
+          node-version: "24"
+          registry-url: "https://registry.npmjs.org"
+          cache: "npm"
+      - run: npm ci
+      - run: npm run check
+      - run: npm publish --access public --tag "${{ github.event.inputs.tag }}"
+```
+
+After npm Trusted Publishing is configured for this exact repo and workflow,
+`npm publish` should authenticate through OIDC without an npm token.
+
+## npm Trusted Publisher Setup
+
+In npm package settings, configure a trusted publisher for:
+
+- provider: GitHub Actions
+- organization/user: `vucinatim`
+- repository: `agentic-devtools`
+- workflow file: `.github/workflows/publish.yml`
+- environment: only if the workflow uses one
+
+The workflow must keep:
+
+```yaml
+permissions:
+  id-token: write
+```
+
+## Package Metadata
+
+The public package should include:
+
+```json
+{
+  "name": "@vucinatim/agentic-devtools",
+  "version": "0.1.0",
+  "private": false,
+  "description": "MCP-first devtools for AI agents.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vucinatim/agentic-devtools.git"
+  },
+  "homepage": "https://github.com/vucinatim/agentic-devtools#readme",
+  "bugs": {
+    "url": "https://github.com/vucinatim/agentic-devtools/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}
+```
+
+## Pre-Publish Checks
+
+Before every release:
+
+- run tests
+- run typecheck
+- run build
+- inspect `npm pack --dry-run`
+- verify no credential files are included
+- verify CLI entrypoint works from packed output
+- verify README examples are current
+
+`npm pack --dry-run` is mandatory before first publish.

package/docs/testing.md

@@ -0,0 +1,61 @@
+# Testing
+
+Agentic Devtools uses Vitest for package tests.
+
+The test suite should validate three layers:
+
+- service clients and auth resolution
+- shared core helpers and registry behavior
+- public package surfaces such as MCP-first CLI commands and exports
+
+## Commands
+
+```bash
+npm test
+npm run test:namecheap
+npm run test:railway
+npm run coverage
+npm run check
+```
+
+`npm run check` is the CI gate. It runs:
+
+1. syntax validation for JavaScript source and test files
+2. Vitest with coverage thresholds
+3. production dependency audit
+4. package dry-run validation
+
+## Coverage Scope
+
+Coverage measures library code under `src/`, excluding:
+
+- `src/cli.mjs`
+- `src/tools/*/mcp.mjs`
+
+Those files are integration entrypoints. Their behavior should be covered by
+CLI smoke tests and MCP-level tests, not line-by-line unit coverage.
+
+Current minimum thresholds:
+
+- statements: 65%
+- branches: 50%
+- functions: 65%
+- lines: 65%
+
+Raise these as the browser auth flow and MCP entrypoints get more direct test
+coverage.
+
+## Package Validation
+
+`npm run validate:package` runs `npm pack --dry-run --json` and verifies that
+the public tarball:
+
+- includes required runtime files
+- excludes tests
+- excludes GitHub workflow files
+- excludes local auth files
+- excludes environment files
+- excludes generated tarballs
+
+This is mandatory for a public package because package contents are part of the
+security boundary.

package/docs/usage.md

@@ -0,0 +1,144 @@
+# Usage
+
+Agentic Devtools is primarily an MCP server package.
+
+The default user should configure their agent host to run a specific tool with
+`npx`. They do not need to add Agentic Devtools to their application
+dependencies.
+
+Run guided setup once if you want credentials stored locally instead of inline
+in MCP host config:
+
+```bash
+npx -y @vucinatim/agentic-devtools connect railway
+npx -y @vucinatim/agentic-devtools connect namecheap
+npx -y @vucinatim/agentic-devtools connect npm
+```
+
+## Primary: MCP Host With `npx`
+
+Use this for Codex, Claude, or any MCP-compatible host.
+
+Railway:
+
+```json
+{
+  "mcpServers": {
+    "railway": {
+      "command": "npx",
+      "args": ["-y", "@vucinatim/agentic-devtools", "mcp", "railway"],
+      "env": {
+        "RAILWAY_API_TOKEN": "..."
+      }
+    }
+  }
+}
+```
+
+If `connect railway` has already saved a token locally, omit the `env` block.
+
+Namecheap:
+
+```json
+{
+  "mcpServers": {
+    "namecheap": {
+      "command": "npx",
+      "args": ["-y", "@vucinatim/agentic-devtools", "mcp", "namecheap"],
+      "env": {
+        "NAMECHEAP_API_USER": "...",
+        "NAMECHEAP_API_KEY": "...",
+        "NAMECHEAP_USERNAME": "...",
+        "NAMECHEAP_CLIENT_IP": "..."
+      }
+    }
+  }
+}
+```
+
+If `connect namecheap` has already saved credentials locally, omit the `env`
+block.
+
+npm:
+
+```json
+{
+  "mcpServers": {
+    "npm": {
+      "command": "npx",
+      "args": ["-y", "@vucinatim/agentic-devtools", "mcp", "npm"]
+    }
+  }
+}
+```
+
+Use `connect npm` for guided token setup when package inspection or token
+operations require authentication.
+
+## Secondary: Global CLI
+
+Install globally only if you want repeated terminal access without `npx`:
+
+```bash
+npm install -g @vucinatim/agentic-devtools
+agentic-devtools tools
+agentic-devtools connect railway
+agentic-devtools connect npm
+agentic-devtools auth-status railway
+agentic-devtools test-connection railway
+```
+
+## Tertiary: Project Dependency
+
+Install into a project only when you want to build custom automation using the
+service clients:
+
+```bash
+npm install @vucinatim/agentic-devtools
+```
+
+```js
+import { createRailwayClient } from "@vucinatim/agentic-devtools";
+import { createNamecheapClient } from "@vucinatim/agentic-devtools";
+import { createNpmClient } from "@vucinatim/agentic-devtools";
+```
+
+## Auth
+
+Railway supports:
+
+- guided local setup through `agentic-devtools connect railway`
+- `RAILWAY_PROJECT_TOKEN` for project-scoped inspection
+- `RAILWAY_API_TOKEN` or `RAILWAY_TOKEN` for account-scoped inspection
+- `RAILWAY_PROJECT_ID` as an optional default project id
+
+Namecheap supports:
+
+- guided local setup through `agentic-devtools connect namecheap`
+- `NAMECHEAP_API_USER`
+- `NAMECHEAP_API_KEY`
+- `NAMECHEAP_USERNAME`
+- `NAMECHEAP_CLIENT_IP`
+- `NAMECHEAP_API_SANDBOX=1` for sandbox usage
+- `NAMECHEAP_API_BASE_URL` for an explicit endpoint override
+
+npm supports:
+
+- guided local setup through `agentic-devtools connect npm`
+- `NPM_TOKEN`
+- `NODE_AUTH_TOKEN`
+- `.npmrc` auth token resolution
+- `NPM_CONFIG_REGISTRY` for registry override
+
+For publishing, prefer GitHub Actions Trusted Publishing. Local publishing is
+available through the npm MCP client but defaults to dry-run and requires an
+explicit confirmation string for real publishes.
+
+## Usage Philosophy
+
+This package should feel like a focused tool belt for agents:
+
+- MCP execution via `npx` is the normal path
+- global CLI is a convenience path
+- project dependency usage is for custom builders
+- host adapters should stay thin and point back to the same package runtime

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@vucinatim/agentic-devtools",
+  "version": "0.1.0",
+  "private": false,
+  "description": "MCP-first devtools for AI agents.",
+  "type": "module",
+  "license": "MIT",
+  "author": {
+    "name": "Tim Vucina",
+    "email": "tim@vucina.com",
+    "url": "https://github.com/vucinatim"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vucinatim/agentic-devtools.git"
+  },
+  "homepage": "https://github.com/vucinatim/agentic-devtools#readme",
+  "bugs": {
+    "url": "https://github.com/vucinatim/agentic-devtools/issues"
+  },
+  "keywords": [
+    "agentic-devtools",
+    "mcp",
+    "mcp-server",
+    "agents",
+    "ai-agents",
+    "namecheap",
+    "railway",
+    "npm",
+    "developer-tools"
+  ],
+  "bin": {
+    "agentic-devtools": "src/cli.mjs"
+  },
+  "exports": {
+    ".": "./src/index.mjs",
+    "./namecheap": "./src/tools/namecheap/client.mjs",
+    "./railway": "./src/tools/railway/client.mjs",
+    "./npm": "./src/tools/npm/client.mjs"
+  },
+  "files": [
+    "src",
+    "adapters",
+    "docs",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "node scripts/check-syntax.mjs",
+    "check": "npm run build && npm run coverage && npm run audit && npm run validate:package",
+    "coverage": "vitest run --coverage",
+    "audit": "npm audit --omit=dev",
+    "pack:dry": "npm pack --dry-run",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:namecheap": "vitest run tests/tools/namecheap",
+    "test:railway": "vitest run tests/tools/railway",
+    "validate:package": "node scripts/validate-package.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "fast-xml-parser": "^5.8.0",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "@emnapi/core": "^1.10.0",
+    "@emnapi/runtime": "^1.10.0",
+    "@vitest/coverage-v8": "^4.1.6",
+    "vitest": "^4.1.6"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+
+import { printJson } from "./core/result.mjs";
+import { getTool, listTools } from "./core/tool-registry.mjs";
+
+const usage = () => `Usage:
+  agentic-devtools tools
+  agentic-devtools mcp <namecheap|railway|npm>
+  agentic-devtools connect <namecheap|railway|npm>
+  agentic-devtools disconnect <namecheap|railway|npm>
+  agentic-devtools auth-status <namecheap|railway|npm>
+  agentic-devtools test-connection <namecheap|railway|npm>
+
+Environment:
+  Namecheap: NAMECHEAP_API_USER, NAMECHEAP_API_KEY, NAMECHEAP_USERNAME, NAMECHEAP_CLIENT_IP
+  Railway:   RAILWAY_PROJECT_TOKEN or RAILWAY_API_TOKEN / RAILWAY_TOKEN
+  npm:       NPM_TOKEN or NODE_AUTH_TOKEN
+`;
+
+const args = process.argv.slice(2);
+
+if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+  process.stdout.write(usage());
+  process.exit(0);
+}
+
+if (args[0] === "tools") {
+  printJson(listTools());
+  process.exit(0);
+}
+
+if (args[0] === "mcp") {
+  const toolName = args[1];
+  if (!toolName) {
+    throw new Error("Missing tool name for mcp command.");
+  }
+  const tool = getTool(toolName);
+  await import(tool.mcpModule);
+  process.exit(0);
+}
+
+if (args[0] === "auth-status") {
+  const toolName = args[1];
+  if (toolName === "namecheap") {
+    const { getAuthStatus } = await import("./tools/namecheap/auth.mjs");
+    printJson(await getAuthStatus());
+    process.exit(0);
+  }
+  if (toolName === "railway") {
+    const { getRailwayAuthStatus } = await import("./tools/railway/client.mjs");
+    printJson(getRailwayAuthStatus());
+    process.exit(0);
+  }
+  if (toolName === "npm") {
+    const { getNpmAuthStatus } = await import("./tools/npm/auth.mjs");
+    printJson(getNpmAuthStatus());
+    process.exit(0);
+  }
+  throw new Error("auth-status expects one of: namecheap, railway, npm");
+}
+
+if (args[0] === "connect") {
+  const toolName = args[1];
+  if (toolName === "namecheap") {
+    const { runBrowserAuthFlow } = await import("./tools/namecheap/auth.mjs");
+    process.stderr.write("Opening Namecheap browser setup flow...\n");
+    printJson(await runBrowserAuthFlow());
+    process.exit(0);
+  }
+  if (toolName === "railway") {
+    const { runRailwayBrowserAuthFlow } = await import(
+      "./tools/railway/auth.mjs"
+    );
+    process.stderr.write("Opening Railway browser setup flow...\n");
+    printJson(await runRailwayBrowserAuthFlow());
+    process.exit(0);
+  }
+  if (toolName === "npm") {
+    const { runNpmBrowserAuthFlow } = await import("./tools/npm/auth.mjs");
+    process.stderr.write("Opening npm browser setup flow...\n");
+    printJson(
+      await runNpmBrowserAuthFlow({
+        onReady: ({ url }) => {
+          process.stderr.write(`npm setup URL: ${url}\n`);
+        },
+      }),
+    );
+    process.exit(0);
+  }
+  throw new Error("connect expects one of: namecheap, railway, npm");
+}
+
+if (args[0] === "disconnect") {
+  const toolName = args[1];
+  if (toolName === "namecheap") {
+    const { disconnectNamecheap } = await import("./tools/namecheap/auth.mjs");
+    printJson(await disconnectNamecheap());
+    process.exit(0);
+  }
+  if (toolName === "railway") {
+    const { disconnectRailway } = await import("./tools/railway/auth.mjs");
+    printJson(await disconnectRailway());
+    process.exit(0);
+  }
+  if (toolName === "npm") {
+    const { disconnectNpm } = await import("./tools/npm/auth.mjs");
+    printJson(await disconnectNpm());
+    process.exit(0);
+  }
+  throw new Error("disconnect expects one of: namecheap, railway, npm");
+}
+
+if (args[0] === "test-connection") {
+  const toolName = args[1];
+  if (toolName === "namecheap") {
+    const { createResolvedNamecheapClient } = await import(
+      "./tools/namecheap/client.mjs"
+    );
+    const client = await createResolvedNamecheapClient();
+    const result = await client.listDomains({ page: 1, pageSize: 1 });
+    printJson({
+      ok: true,
+      domainCount: result.paging.totalItems,
+      sampleDomains: result.domains.slice(0, 1).map((domain) => domain.name),
+      baseUrl: client.baseUrl,
+    });
+    process.exit(0);
+  }
+  if (toolName === "railway") {
+    const { createRailwayClient } = await import("./tools/railway/client.mjs");
+    const client = createRailwayClient();
+    const result =
+      client.auth.kind === "project"
+        ? await client.getProjectTokenContext()
+        : await client.getCurrentViewer();
+    printJson({
+      ok: true,
+      tokenSource: client.auth.source,
+      tokenKind: client.auth.kind,
+      result,
+    });
+    process.exit(0);
+  }
+  if (toolName === "npm") {
+    const { createNpmClient } = await import("./tools/npm/client.mjs");
+    const client = createNpmClient();
+    printJson({
+      ok: true,
+      tokenSource: client.auth.source,
+      registry: client.registry,
+      user: await client.getCurrentUser(),
+    });
+    process.exit(0);
+  }
+  throw new Error("test-connection expects one of: namecheap, railway, npm");
+}
+
+throw new Error(`Unknown command "${args[0]}".\n\n${usage()}`);