@vucinatim/agentic-devtools 0.1.0

package/docs/architecture.md

@@ -0,0 +1,208 @@
+# Architecture
+
+Agentic Devtools should be a small, professional open-source package for
+agent-friendly developer integrations.
+
+The core idea is simple:
+
+- one package contains all tools
+- each tool owns its service-specific client and schemas
+- a shared registry exposes tools through MCP-first CLI execution
+- host-specific integrations stay thin and replaceable
+
+## Package Strategy
+
+Use one public npm package for now:
+
+```txt
+@vucinatim/agentic-devtools
+```
+
+This is the right default because the current tools have the same audience,
+runtime, release cadence, and MCP shape. Separate packages would add release and
+coordination overhead before the project has enough tool-specific complexity to
+need it.
+
+Split into separate packages only when one of these becomes true:
+
+- a tool has a large dependency tree that should not ship to everyone
+- a tool has a materially different runtime target
+- a tool needs independent versioning because users depend on it separately
+- the package grows enough that install size becomes a real problem
+
+Until then, keep a single package and expose separate entrypoints.
+
+## Usage Model
+
+The primary usage path is MCP execution through `npx`:
+
+```bash
+npx -y @vucinatim/agentic-devtools mcp railway
+npx -y @vucinatim/agentic-devtools mcp namecheap
+npx -y @vucinatim/agentic-devtools mcp npm
+```
+
+This keeps Agentic Devtools out of the user's application dependency tree.
+
+Secondary paths:
+
+- global CLI install for repeated terminal use
+- package dependency install for users building custom automation
+
+Account setup should follow the shared auth/setup model in
+[Auth And Setup Guidelines](auth-and-setup-guidelines.md).
+
+## Target Layout
+
+```txt
+agentic-devtools/
+  src/
+    cli.ts
+    index.ts
+    core/
+      config-store.ts
+      mcp-server.ts
+      result.ts
+      tool-registry.ts
+    tools/
+      namecheap/
+        auth.ts
+        client.ts
+        index.ts
+        mcp.ts
+        schemas.ts
+      railway/
+        auth.ts
+        client.ts
+        index.ts
+        mcp.ts
+        schemas.ts
+      npm/
+        auth.ts
+        client.ts
+        index.ts
+        mcp.ts
+        schemas.ts
+  adapters/
+    codex/
+      namecheap/
+      railway/
+    claude/
+      namecheap/
+      railway/
+  tests/
+    tools/
+      namecheap/
+      railway/
+  docs/
+```
+
+The earlier `plugins/<tool>/src` bootstrap layout has been retired. The package
+now has one source tree, one CLI, and one release flow.
+
+## Public API Shape
+
+The package should expose MCP execution through the CLI first, then
+programmatic imports for custom builders.
+
+Example package surface:
+
+```json
+{
+  "name": "@vucinatim/agentic-devtools",
+  "bin": {
+    "agentic-devtools": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./namecheap": {
+      "types": "./dist/tools/namecheap/index.d.ts",
+      "import": "./dist/tools/namecheap/index.js"
+    },
+    "./railway": {
+      "types": "./dist/tools/railway/index.d.ts",
+      "import": "./dist/tools/railway/index.js"
+    }
+  }
+}
+```
+
+Example CLI usage:
+
+```bash
+npx -y @vucinatim/agentic-devtools mcp namecheap
+npx -y @vucinatim/agentic-devtools mcp railway
+npx -y @vucinatim/agentic-devtools mcp npm
+npx -y @vucinatim/agentic-devtools connect railway
+npx @vucinatim/agentic-devtools auth-status railway
+```
+
+## Tool Boundaries
+
+Each tool module should own:
+
+- auth resolution for that service
+- API client calls
+- request and response schemas
+- MCP tool registration for that service
+- tests for API parsing, auth behavior, and dangerous edge cases
+
+The shared core should own:
+
+- local config file read/write helpers
+- common tool-result formatting
+- shared MCP server setup
+- CLI routing
+- registry lookup
+- consistent error shape
+
+The shared core should not know service-specific API details.
+
+## Write Operations
+
+Default new integrations to read-only.
+
+Add write tools only when the workflow has:
+
+- explicit user intent
+- narrow inputs
+- a dry-run or preview path when possible
+- clear idempotency behavior
+- tests for no-op, duplicate, and failure cases
+
+Railway should remain read-only until deployment, variable mutation, and service
+changes have a proper confirmation model.
+
+Namecheap already has DNS mutation tools. Those should continue to prefer
+preserving existing state and should clearly label full-zone replacement as
+destructive.
+
+npm supports publishing operations, but GitHub Actions Trusted Publishing should
+remain the preferred release path. Local npm publishing must default to dry-run
+and require an exact confirmation string for real publishes.
+
+## Host Adapters
+
+Codex and Claude adapters should be metadata and launch wrappers only.
+
+Published host configs should prefer:
+
+```json
+{
+  "command": "npx",
+  "args": ["-y", "@vucinatim/agentic-devtools", "mcp", "<tool>"]
+}
+```
+
+They should not duplicate:
+
+- service clients
+- GraphQL or REST calls
+- mutation logic
+- tool validation rules
+
+If a host needs a custom shape, adapt at the edge and call the shared tool
+module underneath.

package/docs/auth-and-setup-guidelines.md

@@ -0,0 +1,261 @@
+# Auth And Setup Guidelines
+
+Agentic Devtools should make account setup as low-friction as each provider
+honestly allows.
+
+The ideal user experience is:
+
+```bash
+npx -y @vucinatim/agentic-devtools connect <tool>
+```
+
+After that, MCP host config should not need tokens inline:
+
+```json
+{
+  "mcpServers": {
+    "railway": {
+      "command": "npx",
+      "args": ["-y", "@vucinatim/agentic-devtools", "mcp", "railway"]
+    }
+  }
+}
+```
+
+The local MCP server should resolve stored credentials automatically.
+
+## Core Setup Commands
+
+Every tool should eventually support the same setup command shape:
+
+```bash
+agentic-devtools connect <tool>
+agentic-devtools disconnect <tool>
+agentic-devtools auth-status <tool>
+agentic-devtools test-connection <tool>
+```
+
+Shared CLI behavior belongs in `src/cli.mjs` and shared helpers under
+`src/core/`.
+
+Provider-specific auth details belong inside each tool:
+
+```txt
+src/tools/<tool>/auth.mjs
+src/tools/<tool>/client.mjs
+```
+
+Do not make host adapters own auth logic.
+
+## Credential Storage
+
+Store credentials outside project folders by default:
+
+```txt
+~/.config/agentic-devtools/
+  railway.json
+  namecheap.json
+```
+
+Rules:
+
+- never store credentials in the consuming project
+- never require MCP host config to contain secrets after `connect`
+- allow environment variables for stateless CI/server setups
+- environment variables should override stored local credentials
+- `disconnect <tool>` should remove local stored credentials for that tool
+- auth status commands must never print token values
+
+## Provider Auth Tiers
+
+Not every service can support one-click setup. Each tool should document its
+friction level honestly.
+
+### Tier 1: OAuth / One-Click
+
+Best case:
+
+1. user runs `connect <tool>`
+2. browser opens provider OAuth
+3. user approves access
+4. local callback captures auth code
+5. package exchanges code with PKCE
+6. token is stored locally
+7. `mcp <tool>` works without extra host config
+
+Use this when the provider supports OAuth for user-delegated access.
+
+### Tier 2: Guided Token Setup
+
+Use when provider supports API tokens but not first-class OAuth.
+
+Flow:
+
+1. user runs `connect <tool>`
+2. browser opens a local setup page
+3. page links directly to the provider token screen
+4. user creates/pastes token
+5. package validates token
+6. package stores token locally
+
+This is not true one-click, but it can still feel guided and low-friction.
+
+### Tier 3: Guided Manual Setup
+
+Use when provider requires extra account-side configuration, such as IP
+allowlisting.
+
+Flow:
+
+1. user runs `connect <tool>`
+2. browser opens a local setup page
+3. page explains exact provider steps
+4. page detects and displays needed local facts when possible
+5. user performs provider-side setup
+6. user pastes credentials
+7. package validates credentials
+8. package stores credentials locally
+
+This is the lowest honest friction for providers that require manual controls.
+
+## Railway
+
+Railway should aim for Tier 1 eventually.
+
+Railway supports the public API through tokens, and Railway docs describe
+“Login with Railway” OAuth for apps acting on behalf of users.
+
+Recommended path:
+
+1. implement `connect railway` with guided token setup first
+2. store token in `~/.config/agentic-devtools/railway.json`
+3. support:
+   - `RAILWAY_PROJECT_TOKEN`
+   - `RAILWAY_API_TOKEN`
+   - `RAILWAY_TOKEN`
+   - `RAILWAY_PROJECT_ID`
+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
+- do not ask for account token when a project token is enough
+
+## Namecheap
+
+Namecheap is Tier 3.
+
+Namecheap API access requires:
+
+- API access enabled in the account
+- API user
+- API key
+- username
+- client IPv4
+- whitelisted IPv4 address
+
+The setup flow should therefore be guided:
+
+1. `connect namecheap`
+2. open local browser setup page
+3. display current public IPv4 if it can be detected
+4. link to Namecheap API access page
+5. explain IP whitelist requirement
+6. accept API credentials
+7. validate with a lightweight API call
+8. store credentials in `~/.config/agentic-devtools/namecheap.json`
+
+Do not describe Namecheap as one-click unless we later build a hosted connector
+with a stable egress IP and explicit security model.
+
+## npm
+
+npm is Tier 2 for local tools and Tier 1 for CI publishing.
+
+For local MCP use, npm does not provide a normal third-party OAuth flow. Use a
+guided token setup:
+
+1. `connect npm`
+2. open local browser setup page
+3. link to npm granular access token settings
+4. explain least-privilege token selection
+5. accept token
+6. validate with npm identity endpoint
+7. store token in `~/.config/agentic-devtools/npm.json`
+
+Supported auth sources:
+
+- `NPM_TOKEN`
+- `NODE_AUTH_TOKEN`
+- explicit `.npmrc` auth token
+- local Agentic Devtools npm config
+
+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.
+
+## Hosted Connect Option
+
+A future hosted “Agentic Devtools Connect” service could reduce friction further.
+
+Potential benefits:
+
+- true OAuth-style web connection for providers that support OAuth
+- stable callback URLs
+- hosted token broker
+- stable egress IP for providers that require IP allowlisting
+
+Costs and risks:
+
+- secure secret storage
+- token revocation flows
+- account access auditability
+- uptime responsibility
+- abuse prevention
+- paid infrastructure
+
+Do not introduce hosted auth casually. The open-source package should work
+locally first.
+
+## Security Requirements
+
+Auth flows must follow these rules:
+
+- never print token values
+- never commit credentials
+- store local files with restrictive permissions when possible
+- prefer least-privilege tokens
+- validate credentials before reporting setup success
+- make disconnect explicit and reliable
+- document where credentials are stored
+- keep write tools gated behind narrow, explicit actions
+
+## MCP Authorization Note
+
+For local stdio MCP servers, credentials should be resolved from environment
+variables or local storage. The MCP authorization specification says stdio
+transports should not use the HTTP OAuth flow directly.
+
+If Agentic Devtools later ships a hosted HTTP MCP server, that server should
+follow the MCP authorization model and OAuth best practices.
+
+## Implementation Checklist For New Tools
+
+When adding a new tool, define:
+
+- auth tier: OAuth, guided token, or guided manual
+- required credentials
+- least-privilege recommendation
+- local config file shape
+- env var overrides
+- `connect`
+- `disconnect`
+- `auth-status`
+- `test-connection`
+- MCP host config example
+- security caveats
+
+If a provider cannot support one-click setup, say so directly and provide the
+shortest guided setup path.

package/docs/migration-plan.md

@@ -0,0 +1,55 @@
+# Migration Plan
+
+This plan tracks the move from the original plugin bootstrap layout to a single
+professional public npm package.
+
+## Phase 1: Public Repo Baseline
+
+- choose license: done
+- add `CONTRIBUTING.md`: done
+- add `SECURITY.md`: done
+- remove local credential files from the working tree: done
+- initialize Git
+- create public GitHub repo
+- push initial baseline
+
+## Phase 2: Package Consolidation
+
+- move shared source from `plugins/namecheap/src` into `src/tools/namecheap`: done
+- move shared source from `plugins/railway/src` into `src/tools/railway`: done
+- create `src/core` for registry and result formatting: done
+- create `src/cli.mjs`: done
+- keep adapter metadata thin under `adapters/`: done
+- replace per-plugin package manifests with one root package manifest: done
+
+## Phase 3: TypeScript Build
+
+- add TypeScript
+- add `tsup`
+- add generated `dist`
+- add package `exports`
+- add package `bin`
+- convert tests to run against source or built output consistently
+
+## Phase 4: CI
+
+- add GitHub Actions CI: done
+- run install, tests, and build: done
+- add pull request template: done
+- add issue templates: done
+
+## Phase 5: Publish
+
+- configure npm package metadata: done
+- configure npm Trusted Publishing
+- add manual publish workflow: done
+- run `npm pack --dry-run`
+- publish `0.1.0` under `latest`
+- create GitHub release
+
+## Phase 6: Release Management
+
+Add Changesets only after release cadence justifies it.
+
+Until then, manual version bumps plus a guarded publish workflow are simpler and
+easier to reason about.

package/docs/open-source-readiness.md

@@ -0,0 +1,119 @@
+# Open Source Readiness
+
+This repo is intended to become public. Treat everything committed here as
+publishable by default.
+
+## Repository Identity
+
+Recommended GitHub repo:
+
+```txt
+vucinatim/agentic-devtools
+```
+
+Recommended npm package:
+
+```txt
+@vucinatim/agentic-devtools
+```
+
+The scoped npm name is the better default because it ties ownership to the
+publisher namespace and avoids competing with broad unscoped package names.
+
+As of 2026-05-14, `npm view agentic-devtools` and
+`npm view @vucinatim/agentic-devtools` both returned 404 locally, so both names
+appeared unclaimed at that moment. Check again immediately before first publish.
+
+## Public Repo Checklist
+
+Before creating the GitHub repo:
+
+- remove local credential files from the working tree
+- verify `.gitignore` covers local auth files
+- add a license
+- add `CONTRIBUTING.md`
+- add `SECURITY.md`
+- add CI
+- add release/publishing docs
+- make README accurate for public users
+- ensure package metadata points to the final GitHub URL
+- run tests from a fresh install
+
+## Secret Hygiene
+
+Never commit:
+
+- local Namecheap auth files
+- `.env`
+- `.env.*`
+- API tokens
+- Railway project tokens
+- npm tokens
+- generated local caches
+- `node_modules`
+
+The Namecheap browser auth flow stores credentials outside the repo by default
+under the user's config directory. If `NAMECHEAP_AUTH_CONFIG_PATH` points into
+the repo during local testing, remove that file before committing.
+
+## License
+
+Recommended license: MIT.
+
+Reason: this is a developer tooling package where easy reuse matters more than
+copyleft constraints. MIT also matches common npm ecosystem expectations.
+
+Apache-2.0 is also reasonable if explicit patent language matters more. Pick one
+before the first public commit and keep package manifests consistent.
+
+## Minimum Public Metadata
+
+The published package should include:
+
+- `name`
+- `version`
+- `description`
+- `license`
+- `repository`
+- `homepage`
+- `bugs`
+- `keywords`
+- `bin`
+- `exports`
+- `files`
+- `publishConfig.access`
+
+Keep the package description concrete:
+
+```txt
+MCP-first devtools for AI agents.
+```
+
+Avoid broad claims until the tool catalog is larger.
+
+## Dependency Posture
+
+Keep dependencies boring and few.
+
+Good defaults:
+
+- `@modelcontextprotocol/sdk`
+- `zod`
+- `fast-xml-parser` while Namecheap uses XML
+
+Avoid adding frameworks for small CLI routing or config parsing unless they
+remove real complexity.
+
+## Documentation Standard
+
+Every tool should document:
+
+- what it can do
+- auth variables
+- MCP host configuration
+- read/write safety model
+- exposed MCP tools
+- examples
+- known limitations
+
+The top-level README should stay concise and route deeper details to `docs/`.