capman 0.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,108 @@
+# Contributing to capman
+
+First off — thank you for taking the time to contribute.
+capman is an open source project and welcomes contributions of all kinds.
+
+---
+
+## What we're building
+
+capman is a developer tool that lets AI agents interact with applications
+efficiently — without navigating the UI. If you're here, you probably
+have an idea to make that better. Let's hear it.
+
+---
+
+## Ways to contribute
+
+- **Bug reports** — something broke? Open an issue with steps to reproduce
+- **Feature suggestions** — have an idea? Open an issue and describe it
+- **Code contributions** — fix a bug or build a feature via pull request
+- **New test configs** — tested capman against a real app? Add it to test/
+- **Documentation** — spotted something unclear in the README? Fix it
+
+---
+
+## Getting started locally
+
+```bash
+# Clone the repo
+git clone https://github.com/your-username/capman.git
+cd capman
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run the example
+npm run example
+```
+
+---
+
+## Project structure
+
+```
+src/
+  types.ts       — all TypeScript types (the contract)
+  generator.ts   — generate(), validate(), loadConfig()
+  matcher.ts     — match() and matchWithLLM()
+  resolver.ts    — resolve() for API, nav, and hybrid
+  index.ts       — public SDK entry point + ask()
+bin/
+  capman.js      — CLI (init, generate, validate, inspect)
+examples/
+  basic.ts       — simple runnable example
+test/
+  conduit.config.js      — real world test config (Conduit app)
+  test-conduit.ts        — keyword matcher tests
+  test-conduit-llm.ts    — LLM matcher tests
+```
+
+---
+
+## Before submitting a pull request
+
+1. Run `npm run build` — make sure it compiles clean
+2. Run `npx ts-node examples/basic.ts` — make sure the example works
+3. If you changed matching logic, run `npx ts-node test/test-conduit.ts`
+4. Keep pull requests focused — one thing per PR
+5. Write clear commit messages — say what changed and why
+
+---
+
+## Adding a new test config
+
+If you've tested capman against a real app, we'd love to include it.
+
+1. Create `test/your-app.config.js`
+2. Create `test/test-your-app.ts`
+3. Open a pull request with both files
+4. Include your test results in the PR description
+
+---
+
+## Reporting a bug
+
+Open an issue and include:
+- What you ran
+- What you expected
+- What actually happened
+- Your Node.js version (`node --version`)
+
+---
+
+## Code style
+
+- TypeScript everywhere in `src/`
+- No external runtime dependencies in core src/
+- Keep functions small and focused
+- Add a comment if something isn't obvious
+
+---
+
+## Questions?
+
+Open an issue — no question is too small.

package/README.md

@@ -0,0 +1,208 @@
+# Capman — Capability Manifest Engine
+
+Let AI agents interact with your app **without navigating the UI**.
+
+Instead of an AI blindly clicking through screens to find information,
+capman lets your app declare what it can do — and the AI uses that map
+to get answers directly.
+
+---
+
+## The Problem
+
+When an AI agent needs to answer "are there available seats for Friday?",
+today it navigates your entire app like a tourist with no map:
+
+```
+AI clicks → Home → Explore → Events → Category → Detail → Availability
+```
+
+That's slow, wasteful, and exposes parts of your app the AI shouldn't see.
+
+## The Solution
+
+Your app publishes a **capability manifest** — a machine-readable list of
+everything it can do, what API to call, and what data scope is allowed.
+
+The AI reads the manifest and goes directly to the answer.
+
+```
+User query → match capability → resolve via API or nav → done
+```
+
+---
+
+## Install
+
+```bash
+npm install capman
+```
+
+---
+
+## Quick Start
+
+**1. Create a config file**
+
+```bash
+npx capman init
+```
+
+This creates a `capman.config.js` in your project. Edit it to define
+your app's capabilities.
+
+**2. Generate the manifest**
+
+```bash
+npx capman generate
+```
+
+This reads your config and outputs a `manifest.json`.
+
+**3. Use the SDK in your AI agent**
+
+```typescript
+import { match, resolve, readManifest } from 'capman'
+
+const manifest = readManifest()
+
+// Match a user query to a capability
+const matchResult = match("show me my account details", manifest)
+
+// Resolve it
+const result = await resolve(matchResult, {}, {
+  baseUrl: 'https://api.your-app.com'
+})
+
+console.log(result.apiCalls)  // [{ method: 'GET', url: '...' }]
+console.log(result.navTarget) // '/dashboard/profile'
+```
+
+---
+
+## CLI Commands
+
+| Command | What it does |
+|---|---|
+| `capman init` | Create a starter `capman.config.js` |
+| `capman generate` | Generate `manifest.json` from config |
+| `capman validate` | Validate your manifest for errors |
+| `capman inspect` | Print all capabilities in the manifest |
+
+---
+
+## SDK Reference
+
+### `match(query, manifest)`
+Matches a user query to the best capability using keyword scoring.
+Returns a `MatchResult` with the capability, confidence score, and intent.
+
+### `matchWithLLM(query, manifest, { llm })`
+Same as `match()` but uses an LLM for higher accuracy on ambiguous queries.
+Pass in any LLM function — works with Anthropic, OpenAI, or any local model.
+
+```typescript
+const result = await matchWithLLM("find me something", manifest, {
+  llm: async (prompt) => {
+    const res = await anthropic.messages.create({
+      model: 'claude-sonnet-4-20250514',
+      max_tokens: 500,
+      messages: [{ role: 'user', content: prompt }]
+    })
+    return res.content[0].text
+  }
+})
+```
+
+### `resolve(matchResult, params, options)`
+Executes a matched capability via API call, navigation, or both.
+
+### `ask(query, manifest, options)`
+Convenience function — match + resolve in one call.
+
+```typescript
+const { match, resolution } = await ask("go to settings", manifest)
+```
+
+---
+
+## Capability Config
+
+Each capability in your `capman.config.js` looks like this:
+
+```javascript
+{
+  id: 'get_resource',
+  name: 'Get a resource',
+  description: 'Fetch a resource by ID or name.',  // used for matching
+  examples: [                                        // improves accuracy
+    'Show me resource details',
+    'Find resource by ID',
+  ],
+  params: [
+    {
+      name: 'resource_id',
+      description: 'The resource ID',
+      required: true,
+      source: 'user_query',  // or 'session', 'context', 'static'
+    }
+  ],
+  returns: ['resource', 'metadata'],
+  resolver: {
+    type: 'api',             // 'api', 'nav', or 'hybrid'
+    endpoints: [
+      { method: 'GET', path: '/resources/{resource_id}' }
+    ],
+  },
+  privacy: {
+    level: 'public',         // 'public', 'user_owned', or 'admin'
+    note: 'No auth required'
+  }
+}
+```
+
+---
+
+## Privacy Scopes
+
+| Level | Meaning |
+|---|---|
+| `public` | No auth required |
+| `user_owned` | Requires auth, scoped to current user only |
+| `admin` | Restricted to admin roles |
+
+Privacy scope is declared **per capability** — the AI is scoped to only
+what each capability allows, before resolution happens.
+
+---
+
+## Resolver Types
+
+| Type | When to use |
+|---|---|
+| `api` | Answer lives in a backend API call |
+| `nav` | User needs to be routed to a screen |
+| `hybrid` | Both — fetch data AND navigate |
+
+---
+
+## Honest Limits
+
+**Works well:**
+- Structured data retrieval via APIs
+- Navigating to known app screens
+- Multi-endpoint aggregation
+- Privacy scoping per capability
+- Auto-updating on deploy
+
+**Current limits:**
+- Real-time infra status (is the server down?)
+- UI-only state with no API backing
+- Cross-app orchestration
+- Very ambiguous queries without LLM matcher
+
+---
+
+## License
+
+MIT

package/bin/capman.js

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+'use strict'
+
+const path = require('path')
+const fs   = require('fs')
+
+const args    = process.argv.slice(2)
+const command = args[0]
+const flags   = args.slice(1)
+
+const getFlag = (name) => {
+  const i = flags.indexOf(name)
+  return i !== -1 ? flags[i + 1] : undefined
+}
+
+const c = {
+  reset:  '\x1b[0m',
+  bold:   '\x1b[1m',
+  teal:   '\x1b[36m',
+  yellow: '\x1b[33m',
+  red:    '\x1b[31m',
+  green:  '\x1b[32m',
+  gray:   '\x1b[90m',
+}
+
+const log = {
+  info:    (...a) => console.log(`${c.teal}i${c.reset}`, ...a),
+  success: (...a) => console.log(`${c.green}✓${c.reset}`, ...a),
+  warn:    (...a) => console.log(`${c.yellow}⚠${c.reset}`, ...a),
+  error:   (...a) => console.error(`${c.red}✗${c.reset}`, ...a),
+  blank:   ()     => console.log(),
+}
+
+function header() {
+  console.log()
+  console.log(`${c.bold}${c.teal}  capman${c.reset} ${c.gray}v0.1.0 — Capability Manifest Engine${c.reset}`)
+  console.log(`${c.gray}  ─────────────────────────────────────────${c.reset}`)
+  console.log()
+}
+
+function requireSrc() {
+  const distPath = path.join(__dirname, '..', 'dist', 'index.js')
+  if (fs.existsSync(distPath)) return require(distPath)
+
+  try {
+    require('ts-node/register')
+    return require(path.join(__dirname, '..', 'src', 'index.ts'))
+  } catch {
+    log.error('Cannot find dist/. Run: npx tsc')
+    process.exit(1)
+  }
+}
+
+function cmdHelp() {
+  header()
+  console.log(`${c.bold}  Usage:${c.reset}  node bin/capman.js <command>`)
+  console.log()
+  console.log(`${c.bold}  Commands:${c.reset}`)
+  console.log(`    ${c.teal}init${c.reset}      Create a starter capman.config.js`)
+  console.log(`    ${c.teal}generate${c.reset}  Generate manifest.json from config`)
+  console.log(`    ${c.teal}validate${c.reset}  Validate an existing manifest.json`)
+  console.log(`    ${c.teal}inspect${c.reset}   Print all capabilities in manifest`)
+  console.log()
+  console.log(`${c.bold}  Options:${c.reset}`)
+  console.log(`    ${c.gray}--config    Path to config file  (default: capman.config.js)${c.reset}`)
+  console.log(`    ${c.gray}--out       Output path          (default: manifest.json)${c.reset}`)
+  console.log(`    ${c.gray}--manifest  Manifest to read     (default: manifest.json)${c.reset}`)
+  console.log()
+}
+
+function cmdInit() {
+  header()
+  const outPath = path.resolve(process.cwd(), 'capman.config.js')
+  if (fs.existsSync(outPath)) {
+    log.warn('capman.config.js already exists — not overwriting.')
+    process.exit(0)
+  }
+  const { generateStarterConfig } = requireSrc()
+  fs.writeFileSync(outPath, generateStarterConfig())
+  log.success(`Created ${c.bold}capman.config.js${c.reset}`)
+  log.info(`Edit it with your app's capabilities, then run:`)
+  console.log(`\n    node bin/capman.js generate\n`)
+}
+
+function cmdGenerate() {
+  header()
+  const { loadConfig, generate, writeManifest, validate } = requireSrc()
+
+  const configPath = getFlag('--config')
+  const outPath    = getFlag('--out') ?? 'manifest.json'
+
+  log.info('Loading config...')
+  let config
+  try {
+    config = loadConfig(configPath)
+  } catch (e) {
+    log.error(e.message)
+    process.exit(1)
+  }
+
+  log.info(`Generating manifest for ${c.bold}${config.app}${c.reset}...`)
+  const manifest = generate(config)
+  const result   = validate(manifest)
+
+  for (const w of result.warnings) log.warn(w)
+  for (const e of result.errors)   log.error(e)
+
+  if (!result.valid) {
+    log.error('Manifest has errors — fix them before writing.')
+    process.exit(1)
+  }
+
+  const written = writeManifest(manifest, outPath)
+  log.blank()
+  log.success(`Manifest written to ${c.bold}${written}${c.reset}`)
+  log.info(`${manifest.capabilities.length} capabilities registered`)
+  console.log()
+}
+
+function cmdValidate() {
+  header()
+  const { readManifest, validate } = requireSrc()
+
+  const manifestPath = getFlag('--manifest') ?? 'manifest.json'
+  let manifest
+  try {
+    manifest = readManifest(manifestPath)
+  } catch (e) {
+    log.error(e.message)
+    process.exit(1)
+  }
+
+  log.info(`Validating ${c.bold}${manifestPath}${c.reset}...`)
+  const result = validate(manifest)
+  log.blank()
+
+  for (const w of result.warnings) log.warn(w)
+  for (const e of result.errors)   log.error(e)
+
+  if (result.valid) {
+    log.success(`${manifest.capabilities.length} capabilities — all valid`)
+  } else {
+    log.error(`${result.errors.length} error(s) found.`)
+    process.exit(1)
+  }
+  console.log()
+}
+
+function cmdInspect() {
+  header()
+  const { readManifest } = requireSrc()
+
+  const manifestPath = getFlag('--manifest') ?? 'manifest.json'
+  let manifest
+  try {
+    manifest = readManifest(manifestPath)
+  } catch (e) {
+    log.error(e.message)
+    process.exit(1)
+  }
+
+  console.log(`${c.bold}  App:${c.reset}          ${manifest.app}`)
+  console.log(`${c.bold}  Generated:${c.reset}    ${manifest.generatedAt}`)
+  console.log(`${c.bold}  Capabilities:${c.reset} ${manifest.capabilities.length}`)
+  console.log()
+
+  for (const cap of manifest.capabilities) {
+    const col = cap.resolver.type === 'api' ? c.teal : cap.resolver.type === 'nav' ? c.teal : c.yellow
+    console.log(`  ${c.bold}${cap.name}${c.reset}  ${col}[${cap.resolver.type}]${c.reset}  ${c.gray}${cap.privacy.level}${c.reset}`)
+    console.log(`  ${c.gray}id: ${cap.id}${c.reset}`)
+    console.log(`  ${cap.description}`)
+    if (cap.examples?.length) {
+      console.log(`  ${c.gray}e.g. "${cap.examples[0]}"${c.reset}`)
+    }
+    console.log()
+  }
+}
+
+switch (command) {
+  case 'init':     cmdInit();     break
+  case 'generate': cmdGenerate(); break
+  case 'validate': cmdValidate(); break
+  case 'inspect':  cmdInspect();  break
+  case undefined:
+  case '--help':
+  case '-h':       cmdHelp();     break
+  default:
+    header()
+    log.error(`Unknown command: ${command}`)
+    console.log(`  Run: node bin/capman.js --help\n`)
+    process.exit(1)
+}

package/dist/generator.d.ts

@@ -0,0 +1,8 @@
+import type { CapmanConfig, Manifest, ValidationResult } from './types';
+export declare function generate(config: CapmanConfig): Manifest;
+export declare function loadConfig(configPath?: string): CapmanConfig;
+export declare function writeManifest(manifest: Manifest, outputPath?: string): string;
+export declare function readManifest(manifestPath?: string): Manifest;
+export declare function validate(manifest: Manifest): ValidationResult;
+export declare function generateStarterConfig(): string;
+//# sourceMappingURL=generator.d.ts.map

package/dist/generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../src/generator.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAIvE,wBAAgB,QAAQ,CAAC,MAAM,EAAE,YAAY,GAAG,QAAQ,CAOvD;AAED,wBAAgB,UAAU,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,YAAY,CAsD5D;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,EAAE,UAAU,SAAkB,GAAG,MAAM,CAItF;AAED,wBAAgB,YAAY,CAAC,YAAY,SAAkB,GAAG,QAAQ,CAgBrE;AAED,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,gBAAgB,CA4B7D;AACD,wBAAgB,qBAAqB,IAAI,MAAM,CAoF9C"}