@notis_ai/cli 0.2.1 → 0.2.3

package/dist/scaffolds/notis-random/src/mock-runtime.ts

@@ -0,0 +1,128 @@
+import type { NotisRuntime } from '@notis/sdk';
+
+interface MockDoc {
+  id: string;
+  title: string;
+  properties: Record<string, unknown>;
+  icon?: string | null;
+  databaseSlug?: string;
+  createdAt?: string | null;
+  lastEditedTime?: string | null;
+  contentBlocknote?: Array<Record<string, unknown>> | null;
+  contentMarkdown?: string | null;
+  plainText?: string | null;
+}
+
+const STATE: Record<string, MockDoc[]> = { rolls: [] };
+
+declare global {
+  interface Window {
+    __NOTIS_RANDOM_RUNTIME__?: NotisRuntime;
+  }
+}
+
+export function installMockRuntime(initialRoute: 'home' | 'history' = 'home'): NotisRuntime {
+  const runtime: NotisRuntime = {
+    app: {
+      id: 'dev-notis-random',
+      name: 'Random Number Generator',
+      icon: 'phosphor:dice-five',
+      description: 'Dev preview — data is in-memory only.',
+    },
+    route: currentRoute(initialRoute),
+    context: {},
+
+    listTools: async () => [
+      {
+        name: 'LOCAL_NOTIS_DATABASE_QUERY',
+        inputSchema: { type: 'object', properties: { database_slug: { type: 'string' } } },
+      },
+      {
+        name: 'LOCAL_NOTIS_DATABASE_UPSERT_ROLLS',
+        inputSchema: { type: 'object', properties: {} },
+      },
+    ],
+    callTool: async <TResult = unknown>(name: string, args?: Record<string, unknown>): Promise<TResult> => {
+      if (name === 'LOCAL_NOTIS_DATABASE_QUERY') {
+        const request = args ?? {};
+        const databaseSlug = typeof request.database_slug === 'string' ? request.database_slug : 'rolls';
+        const query = request.query && typeof request.query === 'object'
+          ? request.query as Record<string, unknown>
+          : {};
+        const offset = typeof request.offset === 'number' ? request.offset : 0;
+        const all = STATE[databaseSlug] ?? [];
+        const sliced = all.slice(offset);
+        const pageSize = typeof query.page_size === 'number' ? query.page_size : undefined;
+        return { documents: typeof pageSize === 'number' ? sliced.slice(0, pageSize) : sliced } as TResult;
+      }
+
+      if (name === 'LOCAL_NOTIS_DATABASE_UPSERT_ROLLS') {
+        const request = args ?? {};
+        const docs = STATE.rolls ?? [];
+        const now = new Date().toISOString();
+        const documentId = typeof request.document_id === 'string' ? request.document_id : undefined;
+        const existing = documentId ? docs.find((d) => d.id === documentId) : undefined;
+        const controlKeys = new Set(['document_id', 'title']);
+        const properties = Object.fromEntries(
+          Object.entries(request).filter(([key]) => !controlKeys.has(key)),
+        );
+        const doc: MockDoc = {
+          id: existing?.id ?? `dev-rolls-${Date.now()}`,
+          title: typeof request.title === 'string' ? request.title : existing?.title ?? 'Untitled',
+          properties: { ...(existing?.properties ?? {}), ...properties },
+          databaseSlug: 'rolls',
+          icon: null,
+          createdAt: existing?.createdAt ?? now,
+          lastEditedTime: now,
+        };
+        if (existing) docs[docs.indexOf(existing)] = doc;
+        else docs.unshift(doc);
+        STATE.rolls = docs;
+        return { status: 'success', document: doc } as TResult;
+      }
+
+      throw new Error(`Tool calls unavailable in dev preview (${name}).`);
+    },
+
+    request: async () => {
+      throw new Error('Backend requests unavailable in dev preview.');
+    },
+  };
+
+  window.__NOTIS_RANDOM_RUNTIME__ = runtime;
+  return runtime;
+}
+
+export function setMockRoute(route: 'home' | 'history') {
+  if (window.__NOTIS_RANDOM_RUNTIME__) {
+    window.__NOTIS_RANDOM_RUNTIME__.route = currentRoute(route);
+  }
+}
+
+function currentRoute(route: 'home' | 'history') {
+  if (route === 'history') {
+    return {
+      slug: 'history',
+      path: '/history',
+      name: 'History',
+      icon: null,
+      parentSlug: null,
+      default: false,
+      collection: {
+        database: 'rolls',
+        titleProperty: 'Value',
+        parentProperty: null,
+        sidebar: { mode: 'flat-list' as const, allowCreate: false },
+      },
+    };
+  }
+  return {
+    slug: 'home',
+    path: '/',
+    name: 'Generator',
+    icon: 'phosphor:sparkle',
+    parentSlug: null,
+    default: true,
+    collection: null,
+  };
+}

package/dist/scaffolds/notis-random/tailwind.config.ts

@@ -0,0 +1,43 @@
+import type { Config } from 'tailwindcss';
+import tailwindAnimate from 'tailwindcss-animate';
+
+const config: Config = {
+  darkMode: ['class'],
+  content: ['./app/**/*.{ts,tsx}', './lib/**/*.{ts,tsx}'],
+  theme: {
+    extend: {
+      colors: {
+        border: 'hsl(var(--border))',
+        background: 'hsl(var(--background))',
+        foreground: 'hsl(var(--foreground))',
+        muted: {
+          DEFAULT: 'hsl(var(--muted))',
+          foreground: 'hsl(var(--muted-foreground))',
+        },
+        primary: {
+          DEFAULT: 'hsl(var(--primary))',
+          foreground: 'hsl(var(--primary-foreground))',
+        },
+        accent: {
+          DEFAULT: 'hsl(var(--accent))',
+          foreground: 'hsl(var(--accent-foreground))',
+        },
+        card: {
+          DEFAULT: 'hsl(var(--card))',
+          foreground: 'hsl(var(--card-foreground))',
+        },
+      },
+      borderRadius: {
+        lg: 'var(--radius)',
+        md: 'calc(var(--radius) - 2px)',
+        sm: 'calc(var(--radius) - 4px)',
+      },
+      fontFamily: {
+        mono: ['ui-monospace', 'SFMono-Regular', 'Menlo', 'monospace'],
+      },
+    },
+  },
+  plugins: [tailwindAnimate],
+};
+
+export default config;

package/dist/scaffolds/notis-random/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "preserveSymlinks": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "types": ["vite/client", "node"],
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules", "dist"]
+}

package/dist/scaffolds/notis-random/vite.config.ts

@@ -0,0 +1,11 @@
+import { notisViteConfig } from '@notis/sdk/vite';
+import react from '@vitejs/plugin-react';
+import { defineConfig, type UserConfig } from 'vite';
+import appConfig from './notis.config';
+
+const libConfig = notisViteConfig(appConfig) as unknown as UserConfig;
+
+export default defineConfig({
+  ...libConfig,
+  plugins: [react(), ...((libConfig.plugins as UserConfig['plugins']) ?? [])],
+});

package/dist/scaffolds.json

@@ -0,0 +1,36 @@
+{
+  "source": "apps/*/notis.config.ts",
+  "scaffolds": [
+    {
+      "slug": "notis-database",
+      "name": "Databases",
+      "description": "Read-only catalog and schema explorer for every database in your Notis workspace.",
+      "icon": "phosphor:database",
+      "categories": [
+        "Product & Engineering",
+        "Operations"
+      ],
+      "tagline": "Explore every database and schema in your Notis workspace."
+    },
+    {
+      "slug": "notis-notes",
+      "name": "Notis Notes",
+      "description": "Browse notes by documents, table, or calendar with folders in the sidebar.",
+      "icon": "phosphor:note-pencil",
+      "categories": [
+        "Productivity"
+      ],
+      "tagline": "Folder-based notes with gallery, table, and calendar views."
+    },
+    {
+      "slug": "notis-random",
+      "name": "Random Number Generator",
+      "description": "Generate random numbers with configurable bounds, and keep a history of everything you rolled.",
+      "icon": "phosphor:dice-five",
+      "categories": [
+        "Personal"
+      ],
+      "tagline": "Roll dice, keep history."
+    }
+  ]
+}

package/package.json

@@ -1,21 +1,26 @@
 {
   "name": "@notis_ai/cli",
-  "version": "0.2.1",
-  "description": "Agent-first Notis CLI for apps, databases, and generic tool execution",
+  "version": "0.2.3",
+  "description": "Agent-first Notis CLI for apps and generic tool execution",
   "type": "module",
   "bin": {
     "notis": "bin/notis.js"
   },
   "files": [
     "bin/",
+    "config/",
+    "dist/",
     "src/",
+    "skills/",
     "template/",
     "README.md"
   ],
   "scripts": {
+    "build": "node ./scripts/build-scaffolds.js",
     "docs:generate": "node ./scripts/generate-docs.js",
     "docs:check": "node ./scripts/generate-docs.js --check",
-    "release:prepare": "node ./scripts/prepare-publish.js --apply",
+    "prepack": "npm run build",
+    "release:prepare": "npm run build && node ./scripts/prepare-publish.js --apply",
     "cli:set-mode": "node ./scripts/set-cli-mode.js",
     "test": "node --test"
   },

package/skills/notis-apps/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: notis-apps
+description: Design and package Notis apps. Use when users want an app that groups databases, routes, documents, automations, and skills into one installable Notis product.
+---
+
+# Notis Apps Skill
+
+Use this skill when the user wants to create, edit, debug, or package a Notis app. Notis apps are Vite + React projects that deploy into the Notis Portal as installed apps for the current user or team.
+
+Run the Notis CLI through NPX, for example `npx --package @notis_ai/cli@latest -- notis apps list`. Notis Desktop keeps the CLI auth profile current. This `notis-apps` skill is delivered through normal Notis skill sync for the signed-in user, alongside other curated skills.
+
+## Platform Model
+
+A Notis app is:
+
+- a Vite + React project
+- built with `@notis/sdk`
+- configured through `notis.config.ts`
+- packaged as an ES module bundle with `app.js`, `app.css`, and `manifest.json`
+- rendered by the Notis Portal as a React component, not an iframe
+- connected to Notis data and tools through the Portal-provided runtime and SDK hooks
+
+Use the Notis CLI for the app lifecycle:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis apps init
+npx --package @notis_ai/cli@latest -- notis apps dev
+npx --package @notis_ai/cli@latest -- notis apps build
+npx --package @notis_ai/cli@latest -- notis apps verify
+npx --package @notis_ai/cli@latest -- notis apps create
+npx --package @notis_ai/cli@latest -- notis apps link
+npx --package @notis_ai/cli@latest -- notis apps pull
+npx --package @notis_ai/cli@latest -- notis apps deploy
+npx --package @notis_ai/cli@latest -- notis apps doctor
+```
+
+Use this command form everywhere:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis apps ...
+```
+
+## Hard Rules
+
+- Use React + Vite only. Do not use Next.js or a custom server for app projects.
+- Build standard pages in `app/`. Do not write raw `views/<slug>/index.js` files.
+- Keep navigation in `notis.config.ts` `routes`; each route needs a stable `slug`.
+- Reference existing databases by slug in `notis.config.ts`; do not assume deploy creates databases automatically.
+- Declare runtime tool access in `notis.config.ts` `tools`.
+- Use `@notis/sdk` hooks instead of direct runtime access.
+- Do not rely on `window.__NOTIS_RUNTIME__` or portal-owned DOM hooks.
+- `npx --package @notis_ai/cli@latest -- notis apps deploy` updates an installed app. It does not publish to the public App Store.
+- Public or team App Store publishing is a Portal review flow.
+- Use Phosphor icon names with the `phosphor:` prefix. Do not use emoji icons.
+- Prefer scaffolded shadcn components and portal theme tokens over custom visual systems.
+
+## App Workflow
+
+1. Discover existing apps if needed:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis apps list
+```
+
+2. Start from a scaffold or pull an existing app:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis apps scaffolds list
+npx --package @notis_ai/cli@latest -- notis apps init "My App"
+npx --package @notis_ai/cli@latest -- notis apps pull <app-id> ./my-app
+```
+
+3. Install dependencies and develop:
+
+```bash
+npm install
+npx --package @notis_ai/cli@latest -- notis apps dev
+```
+
+4. Build and verify:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis apps build
+npx --package @notis_ai/cli@latest -- notis apps verify
+```
+
+5. Create or link the remote app, then deploy:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis apps create "My App" .
+npx --package @notis_ai/cli@latest -- notis apps deploy
+```
+
+or:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis apps link <app-id>
+npx --package @notis_ai/cli@latest -- notis apps deploy
+```
+
+## App Structure
+
+Expected project shape:
+
+```text
+notis.config.ts
+vite.config.ts
+app/
+components/
+metadata/
+.notis/output/
+```
+
+`notis.config.ts` owns:
+
+- app metadata: name, title, description, icon, categories, tagline
+- database slug references
+- route definitions
+- tool access
+
+Example:
+
+```ts
+import { defineNotisApp } from '@notis/sdk/config';
+
+export default defineNotisApp({
+  name: 'my-app',
+  title: 'My App',
+  description: 'A focused Notis app.',
+  icon: 'phosphor:squares-four',
+  databases: ['tasks'],
+  routes: [
+    {
+      path: '/',
+      slug: 'tasks',
+      name: 'Tasks',
+      icon: 'phosphor:check-square',
+      default: true,
+    },
+  ],
+  tools: ['LOCAL_NOTIS_DATABASE_QUERY', 'LOCAL_NOTIS_DATABASE_UPSERT_TASKS'],
+});
+```
+
+## Runtime Usage
+
+Use SDK hooks for data and tool access:
+
+```tsx
+import { useTool } from '@notis/sdk';
+
+const query = useTool('LOCAL_NOTIS_DATABASE_QUERY');
+```
+
+Do not fetch Notis backend endpoints directly from app code unless the SDK explicitly requires it. The Portal provides authentication, runtime context, and route rendering.
+
+## Troubleshooting
+
+- If deploy fails with backend connectivity errors, run `npx --package @notis_ai/cli@latest -- notis apps doctor` and check the configured API base.
+- If editing an existing app, use `npx --package @notis_ai/cli@latest -- notis apps pull <app-id>` when source snapshots are available.
+- If the Portal shows a stale bundle, hard refresh the Portal or deploy a new version.
+- If an app route fails to load, run `npx --package @notis_ai/cli@latest -- notis apps verify` and inspect `.notis/output/manifest.json`.

package/skills/notis-apps/cli.md

@@ -0,0 +1,208 @@
+# Notis CLI — App Development Workflow
+
+When running outside the Notis container, use the `notis` CLI to work with Notis Apps locally.
+
+Notis apps are Vite + React projects using `@notis/sdk`. The workflow is init, dev, build, verify, create/link, pull, deploy, and doctor.
+
+Important: `notis apps deploy` updates the linked installed app. It is not an app-store publishing flow.
+
+## Setup
+
+Install and sign into Notis Desktop to keep the CLI profile current. Run the CLI through NPX, for example `npx --package @notis_ai/cli@latest -- notis apps list`. Related skills such as `notis-cli` and `notis-apps` are delivered through normal Notis skill sync for the signed-in user.
+
+For CI, hosted agents, or internal scripts, pass a non-persisted token with `NOTIS_JWT=<token>` and use `--api-base <server-url>` when targeting a non-default server.
+
+## Core Workflow
+
+1. Scaffold a new app:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis apps init
+```
+
+2. Or pull an installed app's saved source snapshot:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis apps pull <app-id> ./my-app
+cd ./my-app
+npm install
+```
+
+3. Develop locally with live reload:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis apps dev
+```
+
+4. Build the production artifact:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis apps build
+```
+
+5. Verify the built artifact headlessly:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis apps verify
+```
+
+6. Link the project if it was not created or pulled from an app, then deploy:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis apps link <app-id>
+npx --package @notis_ai/cli@latest -- notis apps deploy
+```
+
+## Commands
+
+### `npx --package @notis_ai/cli@latest -- notis doctor`
+
+Run a quick CLI health check for config, auth, and API reachability.
+
+When to use: Use this before relying on the CLI in automation or after changing environments.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis doctor`
+- `npx --package @notis_ai/cli@latest -- notis doctor --json`
+
+### `npx --package @notis_ai/cli@latest -- notis apps list`
+
+List apps the current profile can access.
+
+When to use: Discover existing apps before linking or deploying.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis apps list`
+- `npx --package @notis_ai/cli@latest -- notis apps list --json`
+
+### `npx --package @notis_ai/cli@latest -- notis apps init <name> [dir]`
+
+Scaffold a new Notis app project.
+
+When to use: Start a new Notis app. Use --from with a bundled scaffold when one is close to the desired app; otherwise creates the bare Vite + React project.
+
+Options:
+- `--from <slug>` — Start from a bundled scaffold listed by `notis apps scaffolds list`.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis apps scaffolds list`
+- `npx --package @notis_ai/cli@latest -- notis apps init "Mind the Flo"`
+- `npx --package @notis_ai/cli@latest -- notis apps init "My CRM" --from notis-database`
+- `npx --package @notis_ai/cli@latest -- notis apps init "My App" ./my-app`
+
+### `npx --package @notis_ai/cli@latest -- notis apps scaffolds list`
+
+List bundled Notis app scaffolds.
+
+When to use: Discover the fixed scaffold catalog shipped with the CLI before starting a new app.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis apps scaffolds list`
+- `npx --package @notis_ai/cli@latest -- notis apps init "My App" --from notis-database`
+
+### `npx --package @notis_ai/cli@latest -- notis apps create <name> [dir]`
+
+Create a new remote Notis app and optionally link a local project to it.
+
+When to use: Provision a fresh remote app before the first deploy. Pass a project directory to link it immediately.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis apps create "My App"`
+- `npx --package @notis_ai/cli@latest -- notis apps create "My App" .`
+
+### `npx --package @notis_ai/cli@latest -- notis apps dev [dir]`
+
+Develop Notis apps inside the Electron desktop Portal with automatic local bundle reloads.
+
+When to use: Run this inside a single app or a monorepo root with apps/<name>/notis.config.ts. It discovers every app, starts the local bundle server, registers desktop-local dev sessions, and opens the Electron Portal to the local development app.
+
+Options:
+- `--port <number>` — Local bundle server port (default: 5173).
+- `--no-open` — Do not auto-open the desktop Portal local development app.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis apps dev`
+- `npx --package @notis_ai/cli@latest -- notis apps dev ./my-app`
+- `npx --package @notis_ai/cli@latest -- notis apps dev ./workspace --port 5200`
+
+### `npx --package @notis_ai/cli@latest -- notis apps build [dir]`
+
+Build and package the app into .notis/output/.
+
+When to use: Prepare the app for verification or deployment.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis apps build`
+- `npx --package @notis_ai/cli@latest -- notis apps build ./my-app`
+
+### `npx --package @notis_ai/cli@latest -- notis apps verify [dir]`
+
+Headless render smoke each route in a stub-runtime harness.
+
+When to use: After notis apps build, before deploy. Catches render-time crashes and missing runtime calls that the build step cannot detect.
+
+Options:
+- `--routes <slugs>` — Comma-separated route slugs. Default: every route in manifest.
+- `--port <n>` — Loopback port. Default: auto-pick.
+- `--skip-build` — Skip notis apps build; reuse existing .notis/output/.
+- `--mode <mode>` — stub | live. Default stub. Live posts to /portal_views/runtime_query with the CLI JWT.
+- `--no-browser` — Start the harness server and print URLs; do not drive agent-browser.
+- `--keep-open` — Leave server + browser session running after report (for manual triage).
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis apps verify`
+- `npx --package @notis_ai/cli@latest -- notis apps verify --routes notes`
+- `npx --package @notis_ai/cli@latest -- notis apps verify --mode live`
+- `npx --package @notis_ai/cli@latest -- notis apps verify --no-browser  # start the harness, drive agent-browser yourself`
+
+### `npx --package @notis_ai/cli@latest -- notis apps link <app-id> [dir]`
+
+Link a local project to a remote Notis app.
+
+When to use: Connect a local project to an existing app for deployment.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis apps link abc123`
+- `npx --package @notis_ai/cli@latest -- notis apps link abc123 ./my-app`
+
+### `npx --package @notis_ai/cli@latest -- notis apps pull <app-id> [dir]`
+
+Download a Notis app source snapshot into a local project folder.
+
+When to use: Edit an installed app locally. Pulls the persisted source, links the directory to the app/version, then continue with npm install, notis apps dev, notis apps build, and notis apps deploy.
+
+Options:
+- `--force` — Overwrite a non-empty target directory.
+- `--version <n>` — Pull a specific app source version (default: latest).
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis apps pull abc123`
+- `npx --package @notis_ai/cli@latest -- notis apps pull abc123 ./my-app --force`
+
+### `npx --package @notis_ai/cli@latest -- notis apps deploy [dir]`
+
+Build and upload the app to the linked Notis app.
+
+When to use: Ship the installed app to production for the linked user/team app. Requires a linked app (notis apps link). This command does not publish to the app store.
+
+Options:
+- `--app-id <id>` — Override linked app ID.
+- `--skip-build` — Skip the build step (use existing .notis/output/).
+- `--direct` — Upload directly to Supabase storage, bypassing the backend server. Auto-fallback on network errors.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis apps deploy`
+- `npx --package @notis_ai/cli@latest -- notis apps deploy --skip-build`
+- `npx --package @notis_ai/cli@latest -- notis apps deploy --app-id abc123`
+- `npx --package @notis_ai/cli@latest -- notis apps deploy --direct`
+
+### `npx --package @notis_ai/cli@latest -- notis apps doctor [dir]`
+
+Check project health and readiness.
+
+When to use: Diagnose issues with a Notis app project.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis apps doctor`
+- `npx --package @notis_ai/cli@latest -- notis apps doctor ./my-app`
+