@vucinatim/agentic-devtools 0.1.0 → 0.1.2

package/README.md

@@ -23,6 +23,12 @@ npx -y @vucinatim/agentic-devtools connect namecheap
 npx -y @vucinatim/agentic-devtools connect npm
 ```
 
+npm publishing setup can also be driven through the package:
+
+```bash
+npx -y @vucinatim/agentic-devtools setup-publishing npm
+```
+
 Start here:
 
 - [docs/architecture.md](docs/architecture.md)
@@ -118,7 +124,9 @@ npm:
 ```
 
 Use `connect npm` for guided token setup. For real package releases, prefer
-GitHub Actions Trusted Publishing over local write tokens.
+GitHub Actions Trusted Publishing over local write tokens. Use
+`setup-publishing npm` to run npm's official Trusted Publishing setup command
+through the package.
 
 ### Global CLI
 
@@ -167,6 +175,7 @@ Current validation commands:
 ```bash
 npm run build
 npm test
+npm run test:published -- --version <published-version>
 npm run test:namecheap
 npm run test:railway
 npm run coverage

package/adapters/codex/npm/SKILL.md

@@ -23,6 +23,7 @@ publish dry-run.
 
 - `getNpmAuthStatus`
 - `connectNpm`
+- `setupNpmGitHubTrustedPublisher`
 - `disconnectNpm`
 - `testNpmConnection`
 - `getNpmPackageInfo`

package/docs/publishing.md

@@ -155,7 +155,24 @@ After npm Trusted Publishing is configured for this exact repo and workflow,
 
 ## npm Trusted Publisher Setup
 
-In npm package settings, configure a trusted publisher for:
+Use the package-owned setup flow:
+
+```bash
+npx -y @vucinatim/agentic-devtools setup-publishing npm
+```
+
+The flow runs npm's official trust command, using the saved npm token from
+`connect npm` when one is available:
+
+```bash
+npx -y npm@^11.10.0 login --auth-type=web --registry https://registry.npmjs.org
+npx -y npm@^11.10.0 trust github @vucinatim/agentic-devtools --repo vucinatim/agentic-devtools --file publish.yml --yes
+```
+
+This keeps the setup aligned with npm's beta Trusted Publishing flow and lets
+npm handle web/security-key two-factor authentication when required.
+
+For this repository it configures:
 
 - provider: GitHub Actions
 - organization/user: `vucinatim`

package/docs/testing.md

@@ -12,6 +12,7 @@ The test suite should validate three layers:
 
 ```bash
 npm test
+npm run test:published -- --version 0.1.1
 npm run test:namecheap
 npm run test:railway
 npm run coverage
@@ -25,6 +26,20 @@ npm run check
 3. production dependency audit
 4. package dry-run validation
 
+## Published Package Smoke Tests
+
+`npm run test:published -- --version <published-version>` validates the actual
+npm artifact after release. It exercises:
+
+- direct `npx` execution
+- simulated global CLI install with `npm install -g --prefix`
+- project dependency install and ESM imports
+- MCP entrypoint help for each public tool
+
+The publish workflow runs this after `npm publish`, so a release is only
+considered good after the registry-hosted package passes real installation and
+usage checks.
+
 ## Coverage Scope
 
 Coverage measures library code under `src/`, excluding:

package/docs/usage.md

@@ -13,6 +13,7 @@ in MCP host config:
 npx -y @vucinatim/agentic-devtools connect railway
 npx -y @vucinatim/agentic-devtools connect namecheap
 npx -y @vucinatim/agentic-devtools connect npm
+npx -y @vucinatim/agentic-devtools setup-publishing npm
 ```
 
 ## Primary: MCP Host With `npx`
@@ -73,7 +74,9 @@ npm:
 ```
 
 Use `connect npm` for guided token setup when package inspection or token
-operations require authentication.
+operations require authentication. Use `setup-publishing npm` when the package
+needs to attach GitHub Actions Trusted Publishing through npm's official trust
+setup flow.
 
 ## Secondary: Global CLI
 
@@ -125,6 +128,7 @@ Namecheap supports:
 npm supports:
 
 - guided local setup through `agentic-devtools connect npm`
+- guided GitHub Actions Trusted Publishing setup through `agentic-devtools setup-publishing npm`
 - `NPM_TOKEN`
 - `NODE_AUTH_TOKEN`
 - `.npmrc` auth token resolution

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vucinatim/agentic-devtools",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "private": false,
   "description": "MCP-first devtools for AI agents.",
   "type": "module",
@@ -59,6 +59,7 @@
     "audit": "npm audit --omit=dev",
     "pack:dry": "npm pack --dry-run",
     "test": "vitest run",
+    "test:published": "node scripts/test-published-package.mjs",
     "test:watch": "vitest",
     "test:namecheap": "vitest run tests/tools/namecheap",
     "test:railway": "vitest run tests/tools/railway",

package/src/cli.mjs

@@ -7,6 +7,7 @@ const usage = () => `Usage:
   agentic-devtools tools
   agentic-devtools mcp <namecheap|railway|npm>
   agentic-devtools connect <namecheap|railway|npm>
+  agentic-devtools setup-publishing npm
   agentic-devtools disconnect <namecheap|railway|npm>
   agentic-devtools auth-status <namecheap|railway|npm>
   agentic-devtools test-connection <namecheap|railway|npm>
@@ -90,6 +91,33 @@ if (args[0] === "connect") {
   throw new Error("connect expects one of: namecheap, railway, npm");
 }
 
+if (args[0] === "setup-publishing") {
+  const toolName = args[1];
+  if (toolName === "npm") {
+    const { runNpmTrustGithubSetup } = await import(
+      "./tools/npm/trust-cli.mjs"
+    );
+    process.stderr.write(
+      "Running npm's official GitHub Trusted Publishing setup flow...\n",
+    );
+    const result = await runNpmTrustGithubSetup({
+      stdio: "inherit",
+      loginFirst: true,
+    });
+    if (!result.ok) {
+      process.exit(result.status || 1);
+    }
+    printJson({
+      ok: true,
+      command: result.command,
+      args: result.args,
+      tokenSource: result.tokenSource,
+    });
+    process.exit(0);
+  }
+  throw new Error("setup-publishing expects: npm");
+}
+
 if (args[0] === "disconnect") {
   const toolName = args[1];
   if (toolName === "namecheap") {

package/src/core/tool-registry.mjs

@@ -2,17 +2,17 @@ export const tools = {
   namecheap: {
     name: "namecheap",
     description: "Inspect and manage Namecheap domains and DNS.",
-    mcpModule: "../tools/namecheap/mcp.mjs",
+    mcpModule: "./tools/namecheap/mcp.mjs",
   },
   railway: {
     name: "railway",
     description: "Inspect Railway projects, environments, and deployments.",
-    mcpModule: "../tools/railway/mcp.mjs",
+    mcpModule: "./tools/railway/mcp.mjs",
   },
   npm: {
     name: "npm",
     description: "Inspect npm packages, auth, tokens, and publishing setup.",
-    mcpModule: "../tools/npm/mcp.mjs",
+    mcpModule: "./tools/npm/mcp.mjs",
   },
 };
 

package/src/index.mjs

@@ -44,4 +44,9 @@ export {
   encodePackageName,
   NpmRegistryError,
 } from "./tools/npm/client.mjs";
+export {
+  buildNpmWebLoginArgs,
+  buildNpmTrustGithubArgs,
+  runNpmTrustGithubSetup,
+} from "./tools/npm/trust-cli.mjs";
 export { getTool, listTools, tools } from "./core/tool-registry.mjs";

package/src/tools/npm/mcp.mjs

@@ -10,6 +10,7 @@ import {
   runNpmBrowserAuthFlow,
 } from "./auth.mjs";
 import { createNpmClient } from "./client.mjs";
+import { runNpmTrustGithubSetup } from "./trust-cli.mjs";
 
 const HELP_TEXT = `Usage: agentic-devtools mcp npm
 
@@ -21,6 +22,12 @@ Optional environment variables:
   NPM_CONFIG_REGISTRY
   AGENTIC_DEVTOOLS_NPM_AUTH_CONFIG_PATH
 
+Standalone flags:
+  --connect
+  --setup-publishing
+  --auth-status
+  --test-connection
+
 Prefer GitHub Actions Trusted Publishing for real package publishing. Local publishing is supported but explicit confirmation is required.
 `;
 
@@ -75,6 +82,23 @@ const createServer = () => {
       }),
   );
 
+  server.registerTool(
+    "setupNpmGitHubTrustedPublisher",
+    {
+      description:
+        "Run npm's official GitHub Actions Trusted Publisher setup flow. Uses npm@^11.10.0 through npx so security-key 2FA can be handled by npm.",
+      inputSchema: {
+        packageName: packageNameSchema.default("@vucinatim/agentic-devtools"),
+        repository: z.string().min(1).default("vucinatim/agentic-devtools"),
+        workflowFile: z.string().min(1).default("publish.yml"),
+        environment: z.string().optional(),
+        loginFirst: z.boolean().default(true),
+      },
+    },
+    async (args) =>
+      createToolResult(await runNpmTrustGithubSetup(args ?? {})),
+  );
+
   server.registerTool(
     "disconnectNpm",
     {
@@ -320,6 +344,32 @@ if (argv.includes("--connect")) {
   process.exit(0);
 }
 
+if (argv.includes("--setup-publishing")) {
+  process.stdout.write(
+    "Running npm's official GitHub Trusted Publishing setup flow...\n",
+  );
+  const result = await runNpmTrustGithubSetup({
+    stdio: "inherit",
+    loginFirst: true,
+  });
+  if (!result.ok) {
+    process.exit(result.status || 1);
+  }
+  process.stdout.write(
+    `${JSON.stringify(
+      {
+        ok: true,
+        command: result.command,
+        args: result.args,
+        tokenSource: result.tokenSource,
+      },
+      null,
+      2,
+    )}\n`,
+  );
+  process.exit(0);
+}
+
 if (argv.includes("--test-connection")) {
   const client = createNpmClient();
   process.stdout.write(

package/src/tools/npm/trust-cli.mjs

@@ -0,0 +1,144 @@
+import { spawn } from "node:child_process";
+import { chmod, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { DEFAULT_NPM_REGISTRY, resolveNpmAuthConfig } from "./auth.mjs";
+
+export const DEFAULT_NPM_TRUST_CLI_SPEC = "npm@^11.10.0";
+
+const normalizeRegistry = (registry = DEFAULT_NPM_REGISTRY) =>
+  String(registry || DEFAULT_NPM_REGISTRY).replace(/\/+$/, "");
+
+export const buildNpmTrustGithubArgs = ({
+  packageName = "@vucinatim/agentic-devtools",
+  repository = "vucinatim/agentic-devtools",
+  workflowFile = "publish.yml",
+  environment = "",
+  yes = true,
+} = {}) => {
+  const args = [
+    DEFAULT_NPM_TRUST_CLI_SPEC,
+    "trust",
+    "github",
+    String(packageName).trim(),
+    "--repo",
+    String(repository).trim(),
+    "--file",
+    String(workflowFile).trim(),
+  ];
+
+  if (environment) {
+    args.push("--env", String(environment).trim());
+  }
+  if (yes) {
+    args.push("--yes");
+  }
+
+  return args;
+};
+
+export const buildNpmWebLoginArgs = () => [
+  DEFAULT_NPM_TRUST_CLI_SPEC,
+  "login",
+  "--auth-type=web",
+  "--registry",
+  DEFAULT_NPM_REGISTRY,
+];
+
+export const runNpmTrustGithubSetup = async ({
+  env = process.env,
+  stdio = "pipe",
+  loginFirst = false,
+  ...options
+} = {}) => {
+  const auth = resolveNpmAuthConfig(env);
+  const registry = normalizeRegistry(auth.registry);
+  const tempDir = await mkdtemp(path.join(os.tmpdir(), "agentic-npm-trust-"));
+  const userconfigPath = path.join(tempDir, ".npmrc");
+
+  if (auth.token && !loginFirst) {
+    const registryUrl = new URL(registry);
+    await writeFile(
+      userconfigPath,
+      `registry=${registry}/\n//${registryUrl.host}/:_authToken=${auth.token}\n`,
+    );
+    await chmod(userconfigPath, 0o600).catch(() => {});
+  }
+
+  const commandEnv = {
+    ...process.env,
+    ...env,
+    NPM_CONFIG_REGISTRY: registry,
+    ...(auth.token && !loginFirst ? { NPM_CONFIG_USERCONFIG: userconfigPath } : {}),
+  };
+
+  try {
+    if (loginFirst) {
+      const loginArgs = ["-y", ...buildNpmWebLoginArgs()];
+      const loginResult = await spawnCommand("npx", loginArgs, {
+        env: commandEnv,
+        stdio,
+      });
+      if (loginResult.status !== 0) {
+        return {
+          ok: false,
+          status: loginResult.status,
+          command: "npx",
+          args: loginArgs,
+          step: "login",
+          tokenSource: auth.source,
+          stdout: loginResult.stdout,
+          stderr: loginResult.stderr,
+        };
+      }
+    }
+
+    const args = ["-y", ...buildNpmTrustGithubArgs(options)];
+    const result = await spawnCommand("npx", args, {
+      env: commandEnv,
+      stdio,
+    });
+
+    return {
+      ok: result.status === 0,
+      status: result.status,
+      command: "npx",
+      args,
+      step: "trust",
+      tokenSource: auth.source,
+      stdout: result.stdout,
+      stderr: result.stderr,
+    };
+  } finally {
+    await rm(tempDir, { recursive: true, force: true });
+  }
+};
+
+const spawnCommand = (command, args, { env, stdio }) =>
+  new Promise((resolve, reject) => {
+    const shouldCapture = stdio === "pipe";
+    let stdout = "";
+    let stderr = "";
+    const child = spawn(command, args, {
+      env,
+      stdio,
+    });
+
+    if (shouldCapture) {
+      child.stdout?.on("data", (chunk) => {
+        stdout += chunk;
+      });
+      child.stderr?.on("data", (chunk) => {
+        stderr += chunk;
+      });
+    }
+
+    child.on("error", reject);
+    child.on("close", (status) => {
+      resolve({
+        status: status ?? 1,
+        stdout,
+        stderr,
+      });
+    });
+  });