@vucinatim/agentic-devtools 0.1.1 → 0.1.3

package/README.md

@@ -6,6 +6,9 @@ Agentic Devtools is an MCP-first open-source package for developer platforms
 such as Railway, Namecheap, and npm. It is meant to be run directly by MCP hosts with
 `npx`, while still exposing package imports for custom automation.
 
+`npx` is the canonical runtime path. Global install is optional terminal
+convenience only.
+
 Most users should not install this into their app. Point your agent host at the
 tool you need:
 
@@ -85,8 +88,15 @@ Railway:
 }
 ```
 
-After `connect railway`, the same server config can omit `env` because the token
-is resolved from `~/.config/agentic-devtools/railway.json`.
+Use:
+
+- `RAILWAY_API_TOKEN` for Railway account tokens and workspace tokens
+- `RAILWAY_PROJECT_TOKEN` for Railway project tokens
+- `RAILWAY_PROJECT_ID` as an optional default project id for account/workspace
+  token flows
+
+After `connect railway`, the same server config can omit `env` because the
+stored token is resolved from `~/.config/agentic-devtools/railway.json`.
 
 Namecheap:
 
@@ -128,6 +138,14 @@ GitHub Actions Trusted Publishing over local write tokens. Use
 `setup-publishing npm` to run npm's official Trusted Publishing setup command
 through the package.
 
+Trusted Publishing notes:
+
+- npm currently documents Trusted Publishing for GitHub-hosted GitHub Actions,
+  GitLab.com shared runners, and CircleCI cloud
+- npm documents a minimum of Node `22.14.0` and npm CLI `11.5.1` for Trusted
+  Publishing
+- each npm package currently has one Trusted Publisher connection at a time
+
 ### Global CLI
 
 Useful if you use the tools often from a terminal:
@@ -140,6 +158,23 @@ agentic-devtools auth-status railway
 agentic-devtools mcp railway
 ```
 
+If `agentic-devtools` is not found after global install, your shell is not
+exposing npm's global bin path. That is a shell setup issue, most commonly with
+Node version managers such as `fnm` or `nvm`, not a package runtime issue.
+
+Check:
+
+```bash
+npm prefix -g
+```
+
+Then make sure `<that-prefix>/bin` is on your `PATH`, or just use the canonical
+no-install path:
+
+```bash
+npx -y @vucinatim/agentic-devtools tools
+```
+
 ### Project Dependency
 
 Use this only when building your own automation on top of the service clients:
@@ -175,6 +210,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/docs/auth-and-setup-guidelines.md

@@ -9,6 +9,10 @@ The ideal user experience is:
 npx -y @vucinatim/agentic-devtools connect <tool>
 ```
 
+This is intentionally the primary path. A global install can be convenient for
+humans in a terminal, but it depends on the user's shell exposing npm's global
+bin directory and should not be treated as the required onboarding contract.
+
 After that, MCP host config should not need tokens inline:
 
 ```json
@@ -134,15 +138,27 @@ Recommended path:
    - `RAILWAY_API_TOKEN`
    - `RAILWAY_TOKEN`
    - `RAILWAY_PROJECT_ID`
+   - `RAILWAY_API_ENDPOINT`
 4. make env vars override stored config
 5. add OAuth once the app registration and callback flow are ready
 
 Token guidance:
 
-- project token: narrow project-scoped inspection
-- account/workspace token: account identity and project listing
+- account token: broadest scope across the user's resources and workspaces
+- workspace token: scoped to a single workspace, but still sent as bearer auth
+  through `RAILWAY_API_TOKEN` or `RAILWAY_TOKEN`
+- project token: scoped to a single environment and sent through
+  `RAILWAY_PROJECT_TOKEN`
 - do not ask for account token when a project token is enough
 
+Validation guidance:
+
+- do not assume every bearer token can call `me`
+- validate project tokens through a project-token-specific query
+- validate account and workspace tokens through project listing or other
+  workspace-compatible reads
+- keep identity-only queries such as `me` as separate optional capabilities
+
 ## Namecheap
 
 Namecheap is Tier 3.
@@ -196,6 +212,16 @@ For package publishing, prefer GitHub Actions Trusted Publishing through OIDC.
 The local npm tool may support publishing for controlled use cases, but real
 publishes must be explicit and confirmation-gated. Dry-run should be the default.
 
+Current npm Trusted Publishing guidance:
+
+- npm currently documents Trusted Publishing for GitHub-hosted GitHub Actions,
+  GitLab.com shared runners, and CircleCI cloud
+- self-hosted runners are not currently the documented path
+- npm currently documents Node `22.14.0+` and npm CLI `11.5.1+`
+- a package currently has one Trusted Publisher configuration at a time
+- after Trusted Publishing is verified, prefer npm's "disallow tokens" publish
+  setting for stronger security
+
 ## Hosted Connect Option
 
 A future hosted “Agentic Devtools Connect” service could reduce friction further.

package/docs/publishing.md

@@ -32,6 +32,14 @@ permission so npm can verify the workflow identity.
 npm also publishes provenance attestations automatically when Trusted Publishing
 is used from supported CI.
 
+Current npm requirements and limits:
+
+- npm documents Trusted Publishing support for GitHub-hosted GitHub Actions,
+  GitLab.com shared runners, and CircleCI cloud
+- self-hosted runners are not currently the documented path
+- npm documents a minimum of Node `22.14.0` and npm CLI `11.5.1`
+- each package currently has one Trusted Publisher configuration at a time
+
 References:
 
 - <https://docs.npmjs.com/trusted-publishers>
@@ -172,6 +180,10 @@ npx -y npm@^11.10.0 trust github @vucinatim/agentic-devtools --repo vucinatim/ag
 This keeps the setup aligned with npm's beta Trusted Publishing flow and lets
 npm handle web/security-key two-factor authentication when required.
 
+After the Trusted Publisher is verified, npm recommends restricting token-based
+publishing access for the package so Trusted Publishing becomes the normal write
+path.
+
 For this repository it configures:
 
 - provider: GitHub Actions

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,24 @@ 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.
+
+There is also a manual GitHub Actions workflow, `Published Smoke`, which can
+re-run the same checks against any already-published version or against the
+current `latest` release without publishing again.
+
 ## Coverage Scope
 
 Coverage measures library code under `src/`, excluding:

package/docs/usage.md

@@ -6,6 +6,9 @@ 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.
 
+Treat `npx` as the canonical path. Global install is optional shell
+convenience, not the primary contract.
+
 Run guided setup once if you want credentials stored locally instead of inline
 in MCP host config:
 
@@ -36,6 +39,12 @@ Railway:
 }
 ```
 
+Use:
+
+- `RAILWAY_API_TOKEN` for Railway account tokens and workspace tokens
+- `RAILWAY_PROJECT_TOKEN` for Railway project tokens
+- `RAILWAY_PROJECT_ID` as an optional default project id
+
 If `connect railway` has already saved a token locally, omit the `env` block.
 
 Namecheap:
@@ -91,6 +100,23 @@ agentic-devtools auth-status railway
 agentic-devtools test-connection railway
 ```
 
+If the command is not found after `npm install -g`, your shell is not exposing
+npm's global bin directory. This is common with version managers such as `fnm`
+or `nvm`.
+
+Check:
+
+```bash
+npm prefix -g
+```
+
+Then ensure `<that-prefix>/bin` is on your `PATH`, or skip global install and
+use:
+
+```bash
+npx -y @vucinatim/agentic-devtools tools
+```
+
 ## Tertiary: Project Dependency
 
 Install into a project only when you want to build custom automation using the
@@ -112,8 +138,24 @@ 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_API_TOKEN` or `RAILWAY_TOKEN` for account tokens and workspace tokens
 - `RAILWAY_PROJECT_ID` as an optional default project id
+- `RAILWAY_API_ENDPOINT` for endpoint override
+
+Railway token guidance:
+
+- account token: broadest scope across your resources and workspaces
+- workspace token: scoped to one workspace, still passed as bearer auth through
+  `RAILWAY_API_TOKEN` or `RAILWAY_TOKEN`
+- project token: scoped to one environment, passed through
+  `RAILWAY_PROJECT_TOKEN`
+
+Validation behavior:
+
+- project tokens are validated through the `projectToken` query
+- account and workspace tokens are validated through project listing
+- identity-style `me` queries are not treated as the compatibility baseline for
+  all bearer tokens
 
 Namecheap supports:
 
@@ -134,6 +176,16 @@ npm supports:
 - `.npmrc` auth token resolution
 - `NPM_CONFIG_REGISTRY` for registry override
 
+npm publishing guidance:
+
+- prefer GitHub Actions Trusted Publishing over long-lived write tokens
+- npm currently documents Trusted Publishing for GitHub-hosted runners, not
+  self-hosted GitHub Actions runners
+- npm currently documents Node `22.14.0+` and npm CLI `11.5.1+` for Trusted
+  Publishing
+- provenance attestations are generated automatically for public packages
+  published from public repositories through supported Trusted Publishing flows
+
 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vucinatim/agentic-devtools",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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

@@ -160,7 +160,7 @@ if (args[0] === "test-connection") {
     const result =
       client.auth.kind === "project"
         ? await client.getProjectTokenContext()
-        : await client.getCurrentViewer();
+        : await client.validateAccountToken();
     printJson({
       ok: true,
       tokenSource: client.auth.source,

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/tools/railway/auth.mjs

@@ -339,7 +339,7 @@ export const runRailwayBrowserAuthFlow = async ({
             if (client.auth.kind === "project") {
               await client.getProjectTokenContext();
             } else {
-              await client.getCurrentViewer();
+              await client.validateAccountToken();
             }
           }
 

package/src/tools/railway/client.mjs

@@ -103,6 +103,20 @@ export const createRailwayClient = ({
     return data.me;
   };
 
+  const validateAccountToken = async () => {
+    requireAccountToken("validateRailwayAccountToken");
+    const projects = await listProjects({ first: 1, includeDeleted: false });
+    return {
+      ok: true,
+      projectCountSampled: projects.length,
+      sampleProjects: projects.map((project) => ({
+        id: project.id,
+        name: project.name,
+        workspace: project.workspace?.name ?? null,
+      })),
+    };
+  };
+
   const listProjects = async ({
     workspaceId = null,
     includeDeleted = false,
@@ -348,6 +362,7 @@ export const createRailwayClient = ({
     endpoint,
     getAuthStatus: () => getRailwayAuthStatus(env),
     getCurrentViewer,
+    validateAccountToken,
     listProjects,
     getProjectTokenContext,
     getProject,

package/src/tools/railway/mcp.mjs

@@ -91,16 +91,12 @@ const createServer = () => {
             };
           }
 
-          const viewer = await client.getCurrentViewer();
+          const validation = await client.validateAccountToken();
           return {
             ok: true,
             tokenSource: client.auth.source,
             tokenKind: client.auth.kind,
-            viewer: {
-              name: viewer.name,
-              email: viewer.email,
-              workspaceCount: viewer.workspaces.length,
-            },
+            validation,
           };
         }),
       ),
@@ -260,7 +256,7 @@ if (argv.includes("--test-connection")) {
   const result =
     client.auth.kind === "project"
       ? await client.getProjectTokenContext()
-      : await client.getCurrentViewer();
+      : await client.validateAccountToken();
   process.stdout.write(
     `${JSON.stringify(
       {