@odla-ai/cli 0.1.0

package/llms.txt

@@ -0,0 +1,260 @@
+# @odla-ai/cli — LLM context
+
+> Project-neutral CLI for provisioning odla apps, database schemas, AI settings, and local runtime files.
+
+Project-neutral provisioning CLI for odla apps. It creates and validates an
+`odla.config.mjs`, then uses that config to register an app, enable services,
+push odla-db schema/rules, configure platform AI, configure Clerk auth, record
+deployment links, and write local runtime credentials.
+
+It does not know about any specific app. App identity, environments, services,
+schema, rules, auth, AI provider, and links all come from config.
+
+## Install
+
+No install needed — the package ships a single `odla-ai` binary, so npx can run
+it directly:
+
+```bash
+npx @odla-ai/cli init --app-id my-app --name "My App"
+```
+
+For a project you keep working in, install it as a dev dependency so the
+shorter `npx odla-ai` form works and the version is pinned by your lockfile:
+
+```bash
+npm i -D @odla-ai/cli
+```
+
+## Prerequisites
+
+- Node.js 20 or newer (`node --version`).
+- odla apps usually deploy as Cloudflare Workers. If you have never used
+  Cloudflare:
+  1. Create a free account at <https://dash.cloudflare.com/sign-up>.
+  2. You do not need to install anything: `npx wrangler login` opens the
+     browser once to link your account, `npx wrangler dev` runs a Worker
+     locally, and `npx wrangler deploy` ships it.
+  3. The `.dev.vars` file this CLI writes with `provision --write-dev-vars` is
+     wrangler's local secrets file — `wrangler dev` picks it up automatically.
+     It is chmod `0600` and gitignored; never commit it or paste its contents
+     into `wrangler.toml`.
+
+## Commands
+
+```bash
+npx odla-ai init --app-id my-app --name "My App"
+npx odla-ai doctor
+npx odla-ai provision --dry-run
+npx odla-ai provision --write-dev-vars
+npx odla-ai smoke --env dev
+npx odla-ai version
+```
+
+`init` writes:
+
+- `odla.config.mjs`
+- `src/odla/schema.mjs`
+- `src/odla/rules.mjs`
+- `.gitignore` entries for local credentials
+
+`provision` performs the standard safe setup flow:
+
+1. Gets an `odla_dev_...` token by device handshake, or reuses
+   `ODLA_DEV_TOKEN` / `.odla/dev-token.json`.
+   In an interactive terminal it opens the approval page in your browser when
+   the code is displayed. Pass `--open` to force browser launch from a
+   non-interactive shell, or `--no-open` to suppress it. Browser launch is
+   best-effort; the printed URL and code always remain the fallback.
+2. Creates the platform app if needed.
+3. Enables configured services in every configured environment.
+4. Mints or reuses each env's odla-db app key.
+5. Pushes the configured schema and rules.
+6. Configures platform AI and stores provider keys in the tenant vault when the
+   configured key env var is set.
+7. Writes `.odla/credentials.local.json` with mode `0600`.
+
+Pass `--rotate-keys` to mint fresh db keys. Pass `--no-write-credentials` to
+skip writing the local credentials file.
+
+`smoke` verifies a provisioned environment from local credentials. It fetches
+the platform public config, checks the configured AI provider, fetches the live
+odla-db schema with the tenant key, compares expected schema entities, and runs
+a count aggregate against the first entity. It fails early with a clear message
+when provisioning has not written `.odla/credentials.local.json`.
+
+## Config
+
+```js
+export default {
+  platformUrl: process.env.ODLA_PLATFORM_URL ?? "https://odla.ai",
+  dbEndpoint: process.env.ODLA_ENDPOINT ?? process.env.ODLA_DB_ENDPOINT ?? "https://db.odla.ai",
+  app: { id: "my-app", name: "My App" },
+  envs: ["prod", "dev"],
+  services: ["db", "ai"],
+  db: {
+    schema: "./src/odla/schema.mjs",
+    rules: "./src/odla/rules.mjs",
+    defaultRules: "deny",
+  },
+  ai: {
+    provider: process.env.ODLA_AI_PROVIDER ?? "anthropic",
+    keyEnv: "ANTHROPIC_API_KEY",
+  },
+  auth: {
+    clerk: {
+      dev: "$CLERK_PUBLISHABLE_KEY",
+      prod: "$CLERK_PUBLISHABLE_KEY",
+    },
+  },
+  links: {
+    dev: "https://dev.example.com",
+    prod: "https://example.com",
+  },
+};
+```
+
+`db.schema` and `db.rules` may be inline objects, JSON files, or JS modules
+exporting `default`, `schema` / `SCHEMA`, or `rules` / `RULES`.
+
+If schema is present and rules are omitted, `defaultRules: "deny"` generates
+deny-all rules for every schema entity. That is the safe default for Workers
+that mediate reads and writes with an app key.
+
+## API reference (generated from dist/index.d.ts, v0.1.0)
+
+```ts
+declare function runCli(argv?: string[]): Promise<void>;
+
+interface DoctorOptions {
+    configPath: string;
+    stdout?: Pick<typeof console, "log" | "error">;
+}
+declare function doctor(options: DoctorOptions): Promise<void>;
+
+interface InitOptions {
+    rootDir?: string;
+    configPath?: string;
+    appId: string;
+    name: string;
+    envs?: string[];
+    services?: string[];
+    aiProvider?: string;
+    force?: boolean;
+    stdout?: Pick<typeof console, "log" | "error">;
+}
+declare function initProject(options: InitOptions): void;
+
+type OdlaEnvName = string;
+type AppRules = Record<string, {
+    view?: string;
+    create?: string;
+    update?: string;
+    delete?: string;
+}>;
+interface ClerkAuthConfig {
+    publishableKey?: string;
+    audience?: string;
+    mode?: "client" | "full";
+}
+interface OdlaProjectConfig {
+    platformUrl?: string;
+    dbEndpoint?: string;
+    app: {
+        id: string;
+        name: string;
+    };
+    envs?: OdlaEnvName[];
+    services?: string[];
+    db?: {
+        /** Inline SerializedSchema, JSON file, or JS module path exporting default/schema. */
+        schema?: unknown;
+        /** Inline rule map, JSON file, or JS module path exporting default/rules. */
+        rules?: AppRules | string;
+        /** Generate deny-all rules from schema when rules are omitted. Defaults to true when schema exists. */
+        defaultRules?: "deny" | false;
+    };
+    ai?: {
+        provider?: string;
+        model?: string;
+        /** Env var containing the provider key to store in the platform vault. */
+        keyEnv?: string;
+        /** Vault secret name. Defaults to @odla-ai/ai's provider default. */
+        secretName?: string;
+    };
+    auth?: {
+        clerk?: Record<OdlaEnvName, ClerkAuthConfig | string | null | undefined>;
+    };
+    links?: Record<OdlaEnvName, string | null | undefined>;
+    local?: {
+        tokenFile?: string;
+        credentialsFile?: string;
+        devVarsFile?: string;
+        gitignore?: boolean;
+    };
+}
+interface LoadedProjectConfig extends OdlaProjectConfig {
+    configPath: string;
+    rootDir: string;
+    platformUrl: string;
+    dbEndpoint: string;
+    envs: OdlaEnvName[];
+    services: string[];
+    local: {
+        tokenFile: string;
+        credentialsFile: string;
+        devVarsFile: string;
+        gitignore: boolean;
+    };
+}
+interface LocalCredentials {
+    appId: string;
+    platformUrl: string;
+    dbEndpoint: string;
+    updatedAt: string;
+    envs: Record<string, {
+        tenantId: string;
+        dbKey?: string;
+    }>;
+}
+interface ProvisionOptions {
+    configPath: string;
+    dryRun?: boolean;
+    rotateKeys?: boolean;
+    writeCredentials?: boolean;
+    writeDevVars?: string | boolean;
+    token?: string;
+    /** true forces browser launch, false disables it, undefined auto-opens only for interactive terminals. */
+    open?: boolean;
+    /** Test/embedding override for terminal interactivity. Defaults to stdin/stdout TTY detection. */
+    interactive?: boolean;
+    /** Test/embedding override for opening the approval URL. Defaults to the OS browser opener. */
+    openApprovalUrl?: (url: string) => Promise<void>;
+    yes?: boolean;
+    fetch?: typeof fetch;
+    stdout?: Pick<typeof console, "log" | "error">;
+}
+interface ProvisionPlan {
+    appId: string;
+    appName: string;
+    platformUrl: string;
+    dbEndpoint: string;
+    envs: string[];
+    services: string[];
+    hasSchema: boolean;
+    hasRules: boolean;
+    aiProvider?: string;
+}
+interface SmokeOptions {
+    configPath: string;
+    env?: string;
+    fetch?: typeof fetch;
+    stdout?: Pick<typeof console, "log" | "error">;
+}
+
+declare function provision(options: ProvisionOptions): Promise<void>;
+
+declare function smoke(options: SmokeOptions): Promise<void>;
+
+export { type LoadedProjectConfig, type LocalCredentials, type OdlaProjectConfig, type ProvisionOptions, type ProvisionPlan, type SmokeOptions, doctor, initProject, provision, runCli, smoke };
+```

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@odla-ai/cli",
+  "version": "0.1.0",
+  "description": "Project-neutral CLI for provisioning odla apps, database schemas, AI settings, and local runtime files.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "odla-ai": "./dist/bin.js"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "REQUIREMENTS.md",
+    "llms.txt"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "odla",
+    "odla-ai",
+    "cli",
+    "provisioning",
+    "cloudflare",
+    "database",
+    "knowledge-graph",
+    "ai"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "coverage": "vitest run --coverage",
+    "gen:llms": "node ../../scripts/gen-llms.mjs",
+    "prepublishOnly": "npm run build && npm run gen:llms"
+  },
+  "dependencies": {
+    "@odla-ai/ai": "^0.2.1",
+    "@odla-ai/apps": "^0.7.1",
+    "@odla-ai/db": "^0.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  }
+}