@notis_ai/cli 0.2.0-beta.102.1

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

@@ -0,0 +1,129 @@
+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),
+    databases: [],
+    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,47 @@
+{
+  "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-journal",
+      "name": "5 Minutes Journal",
+      "description": "A display-only five-minute journal built from your morning and evening check-ins with Notis. Browse daily mood, energy, motivation, gratitude, intentions, affirmations, highlights, lessons, and free-form reflections, then use Stats to see trends and ritual consistency over time.",
+      "icon": "phosphor:notebook",
+      "categories": [
+        "Personal",
+        "Productivity"
+      ],
+      "tagline": "Five intentional minutes with Notis, split between morning and evening."
+    },
+    {
+      "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

@@ -0,0 +1,45 @@
+{
+  "name": "@notis_ai/cli",
+  "version": "0.2.0-beta.102.1",
+  "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",
+    "prepack": "npm run build",
+    "release:prepare": "npm run build && node ./scripts/prepare-publish.js --apply",
+    "cli:set-mode": "node ./scripts/set-cli-mode.js",
+    "smoke": "node ./scripts/smoke-package.js",
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "sharp": "^0.34.5"
+  },
+  "keywords": [
+    "notis",
+    "cli",
+    "ai",
+    "agent-skills"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}

package/skills/notis-apps/SKILL.md

@@ -0,0 +1,219 @@
+---
+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 screenshot
+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 publish --confirm-ready
+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.
+- **Local development first; deploy is user-gated.** Iterate with `apps dev` and hand off for the **user** to test in the desktop **Local development** sidebar group. Do not run `apps create` / `apps deploy` on your own — a clean build/verify is not permission to deploy. Deploy only when the user has tested the local build and explicitly asks. Finishing a build without deploying is the expected outcome.
+- **Installed app links are explicit.** A mounted dev session updates an installed app only when the checkout is linked by app id in `.notis/state.json` and the active dev-session registry mirrors that id. Name or slug matches may be suggestions, never update targets.
+- **Store submission is separately user-gated.** Run `apps publish --confirm-ready` only after the user explicitly confirms the current App Details page is ready. Deploy that exact approved state first; never infer Store approval from a deploy request.
+- **Bump `notisAppVersion` for every Store update.** `package.json` must contain a semver `notisAppVersion`; increment it beyond the currently published registry version before deploying an update.
+- **Keep release history in one root `CHANGELOG.md`.** Put the newest entry first and use `## [Release title] - YYYY-MM-DD`, or `{PR_MERGE_DATE}` before publication. Do not add new `versionNotes` fields to `notis.config.ts`. App Details reads **What’s New** and **Version History** from the deployed package manifest; the Store reads the latest published snapshot, so unpublished workspace edits never change it. The manifest exposes `package.json` `notisAppVersion` as the package version shown in App Details.
+- Public submissions still use the registry review flow; the CLI invokes the same authenticated submission endpoint as App Details.
+- 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. Keep `apps dev` running and **hand off to the user** — it is what surfaces the app in the desktop **Local development** sidebar group, and letting the user test there is the finish line for a build request:
+
+```bash
+npm install
+npx --package @notis_ai/cli@latest -- notis apps dev
+```
+
+The desktop lists a dev app only if its session is in the per-workspace registry it polls: `<workspace>/.context/app-dev-sessions.json`. A current CLI auto-resolves the nearest `.context` registry; on older CLIs (or when launched outside the workspace), pass `NOTIS_APP_DEV_SESSIONS_FILE="$CONDUCTOR_WORKSPACE_PATH/.context/app-dev-sessions.json"`. After starting, confirm your app's `devSlug` is in that file with a fresh `lastHeartbeatAt` — if it isn't, the session landed in the global `~/.notis` registry and the app won't appear in the sidebar.
+
+4. Build, capture listing screenshots, and verify (still local — this does not deploy):
+
+```bash
+npx --package @notis_ai/cli@latest -- notis apps build
+npx --package @notis_ai/cli@latest -- notis apps screenshot
+npx --package @notis_ai/cli@latest -- notis apps verify
+```
+
+Declare 3–6 screenshots in `notis.config.ts`, each with a `path`, descriptive
+`alt`, and optional `route`/`scenario`/`focus`/`theme`. Use `focus` to crop to a
+real app root instead of empty browser canvas, and use `theme: 'light'` or
+`theme: 'dark'` for a matching Portal render and Store frame. Paired light/dark
+entries may reuse the same route and scenario. `notis apps screenshot` renders
+those configured states in a headless harness and writes exact 2000x1250 PNGs
+under `metadata/`, using the deterministic Store presentation by default. Use
+`--raw` only for an unframed diagnostic capture. Apps are icon-led like Raycast:
+the app icon represents the app everywhere, so there is no cover image — only
+these screenshots. Re-run after changing routes or UI; it overwrites the set and
+drops stale files. Use `--routes home,history` to capture a subset.
+
+5. **Only after the user has tested the local build and explicitly asks to deploy**, create or link the remote app, then deploy (this installs or updates the app on the user's account, where it appears under **Workspace** rather than Local development). After first install, keep `.notis/state.json` linked to that installed app id so future dev-session actions become **Update** instead of another **Install**:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis apps create "My App" .
+npx --package @notis_ai/cli@latest -- notis apps deploy
+```
+
+6. **Only after the user explicitly confirms App Details is ready for Store review**, submit the deployed version:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis apps publish --confirm-ready
+```
+
+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
+CHANGELOG.md        # complete Store release history, newest entry first
+vite.config.ts
+app/
+components/
+metadata/          # screenshot-N.png only — generated by `notis apps screenshot`
+.notis/output/
+```
+
+`metadata/` holds 3–6 listing screenshots (`screenshot-1.png`, `screenshot-2.png`,
+…). Each must be an exact 2000x1250 PNG no larger than 2 MB, with descriptive
+alt text declared in `notis.config.ts`. There is no `cover.png`: apps are icon-led like Raycast and the icon set in
+`notis.config.ts` represents the app in the Store. Generate screenshots with
+`notis apps screenshot` rather than authoring PNGs by hand.
+
+`notis.config.ts` owns:
+
+- app metadata: name, title, description, icon, accent, categories, tagline
+- listing screenshots: stable path, alt text, and optional capture route/scenario/focus/theme
+- database slug references
+- route definitions
+- tool access
+
+`CHANGELOG.md` owns Store release copy. Keep all releases in that single file:
+
+```markdown
+# My App Changelog
+
+## [A Better Workflow] - {PR_MERGE_DATE}
+
+- Added a faster daily workflow.
+
+## [Initial Release] - 2026-07-01
+
+- Published the first version.
+```
+
+Store publication is blocked until the deployed manifest contains at least one
+valid entry. Ordinary local development and deployment still work when an app
+is not being prepared for the Store.
+
+**Icon & accent.** Set `icon` to a `phosphor:<name>` value (e.g. `phosphor:dice-five`) or `metadata/icon.png`. When `icon` is unset, the app shows its **two-letter initials** everywhere (store, sidebar, app details). `accent` optionally pins the avatar color to one of `blue | violet | emerald | amber | rose | sky | fuchsia | teal`; when unset a stable color is derived automatically from the app id. Both flow from `notis.config.ts` through deploy onto the app row and listing, and can also be changed later with the `update_app` tool (`{ "icon": "phosphor:...", "accent": "emerald" }`).
+
+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',
+  accent: 'blue',
+  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`.