@notis_ai/cli 0.2.0-beta.102.1

package/README.md

@@ -0,0 +1,334 @@
+# @notis_ai/cli
+
+Agent-first Notis CLI for apps and generic tool execution.
+
+## Install
+
+Use the Notis CLI through NPX. Install and sign into Notis Desktop to keep the local CLI auth profile current; do not rely on an installed `notis` command. 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>`.
+
+## Quick Start
+
+```bash
+npx --package @notis_ai/cli@latest -- notis --help
+npx --package @notis_ai/cli@latest -- notis doctor
+npx --package @notis_ai/cli@latest -- notis apps list
+npx --package @notis_ai/cli@latest -- notis tools search "list Notis databases"
+```
+
+The desktop app owns sign-in and keeps the CLI profile in sync automatically.
+
+The CLI defaults to `json` output in agent or non-TTY contexts and `table` output in interactive terminals.
+
+## Global Flags
+
+- `--json` — Shortcut for `--output json`
+- `--output <table|json|yaml|ndjson>` — Output mode override
+- `--non-interactive` — Disable prompts
+- `--profile <name>` — Select a stored profile
+- `--api-base <url>` — Override the API base for one invocation
+- `--timeout-ms <n>` — HTTP timeout in milliseconds
+- `--idempotency-key <key>` — Override the generated idempotency key for mutating commands
+
+## Apps
+
+### `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]`
+
+Validate every route and the production Store listing contract.
+
+When to use: After notis apps screenshot, before deploy. Catches render-time crashes, missing runtime calls, and incomplete listing media 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 screenshot [dir]`
+
+Capture configured listing route/scenario states via the headless harness.
+
+When to use: Generate the 3–6 declared metadata/screenshot-N.png files for the App Store listing. Apps are icon-led (like Raycast) — there is no cover image, only these screenshots. Each screenshot may set a focus selector to remove empty canvas and a light or dark theme that also controls its Store frame. Run before notis apps verify / deploy / publish.
+
+Options:
+- `--routes <slugs>` — Comma-separated route slugs. Default: every configured screenshot state.
+- `--port <n>` — Loopback port. Default: auto-pick.
+- `--width <px>` — Viewport width. Default: 2000.
+- `--height <px>` — Viewport height. Default: 1250 (16:10).
+- `--output-dir <dir>` — Where to write screenshot-N.png. Default: metadata/.
+- `--mode <mode>` — stub | live. Default stub. Live renders against real data via the CLI JWT (requires a linked app), so screenshots show actual content instead of empty states.
+- `--raw` — Write the unframed harness capture instead of the default Store presentation.
+- `--skip-build` — Skip notis apps build; reuse existing .notis/output/.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis apps screenshot  # honors notis.config.ts screenshot scenarios`
+- `npx --package @notis_ai/cli@latest -- notis apps screenshot --routes home,history`
+- `npx --package @notis_ai/cli@latest -- notis apps screenshot --mode live  # populated screenshots from real data`
+- `npx --package @notis_ai/cli@latest -- notis apps screenshot --raw  # diagnostic capture without Store framing`
+
+### `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 publish [dir]`
+
+Submit the deployed app for Store review.
+
+When to use: After the user explicitly confirms the App Details page and Store listing are ready. Requires the current local project to match the latest deployed version.
+
+Options:
+- `--app-id <id>` — Override linked app ID.
+- `--confirm-ready` — Confirm the user approved the current App Details page for Store submission.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis apps publish --confirm-ready`
+- `npx --package @notis_ai/cli@latest -- notis apps publish ./my-app --confirm-ready`
+
+### `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`
+
+
+## Generic Tools
+
+### `npx --package @notis_ai/cli@latest -- notis tools toolkits`
+
+List toolkit namespaces and connection statuses available to the active user.
+
+When to use: Use this to inspect connection state before searching or executing generic tools.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis tools toolkits`
+- `npx --package @notis_ai/cli@latest -- notis tools toolkits --json`
+
+### `npx --package @notis_ai/cli@latest -- notis tools search <query>`
+
+Search across toolkit namespaces using natural language.
+
+When to use: Use this when you need a generic capability that does not have a first-class CLI command.
+
+Options:
+- `--known-fields <text>` — Optional known field hints, such as channel_name:general or user_email:a@example.com.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis tools search "send an email"`
+- `npx --package @notis_ai/cli@latest -- notis tools search "post on LinkedIn" --known-fields "platform:linkedin"`
+
+### `npx --package @notis_ai/cli@latest -- notis tools describe <tool-name>`
+
+Describe a generic tool by name.
+
+When to use: Use this when you know the tool name and want its parameter schema before execution.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis tools describe composio-gmail-send_email`
+- `npx --package @notis_ai/cli@latest -- notis tools describe LOCAL_NOTIS_DATABASE_QUERY`
+
+### `npx --package @notis_ai/cli@latest -- notis tools exec <tool-name>`
+
+Execute a generic tool by canonical tool name.
+
+When to use: Use this as the escape hatch for integrations or Notis tools without a first-class CLI wrapper.
+
+Options:
+- `--arguments <json>` — JSON object, @file path, or - for stdin.
+- `--file <argument-path=local-path>` — Upload a local file into a file-uploadable tool argument. Repeatable.
+- `--get-schema` — Display the tool parameter schema without executing.
+- `--dry-run` — Validate arguments against the tool schema without executing.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_QUERY --arguments '{"database_slug":"tasks","query":{}}'`
+- `npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_GET_DATABASE --arguments '{"database_slug":"tasks"}'`
+- `npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_QUERY --get-schema`
+- `npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_QUERY --dry-run --arguments '{"database_slug":"tasks","query":{}}'`
+- `npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_QUERY --arguments @query.json`
+- `npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_QUERY --arguments - < query.json`
+- `npx --package @notis_ai/cli@latest -- notis tools exec composio-dropbox-upload_file --arguments '{"path":"/target/in/dropbox.pdf"}' --file content=./Invoice.pdf`
+
+### `npx --package @notis_ai/cli@latest -- notis tools exec-parallel <calls>`
+
+Execute multiple tools concurrently.
+
+When to use: Use this when you need to run independent tool calls simultaneously for speed.
+
+Options:
+- `--file <argument-path=local-path>` — Unsupported for exec-parallel; use tools exec for file uploads.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis tools exec-parallel '[{"tool_name":"LOCAL_NOTIS_DATABASE_QUERY","arguments":{"database_slug":"tasks","query":{}}},{"tool_name":"LOCAL_NOTIS_DATABASE_LIST_DATABASES","arguments":{}}]'`
+
+### `npx --package @notis_ai/cli@latest -- notis tools link <toolkit>`
+
+Get the URL to connect an integration toolkit.
+
+When to use: Use this when a tool requires authentication with an external service.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis tools link github`
+- `npx --package @notis_ai/cli@latest -- notis tools link gmail --json`
+
+
+## Meta 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 whoami`
+
+Display the active profile, user, and available toolkit connection statuses.
+
+When to use: Use this to quickly confirm which account and environment a command will target.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis whoami`
+- `npx --package @notis_ai/cli@latest -- notis whoami --json`
+
+### `npx --package @notis_ai/cli@latest -- notis describe <command...>`
+
+Describe a first-class CLI command in detail.
+
+When to use: Use this when an agent or human needs the exact shape, examples, and semantics of a command.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis describe apps deploy`
+- `npx --package @notis_ai/cli@latest -- notis describe tools exec`
+
+
+## Local Development
+
+```bash
+cd packages/cli
+npm install
+node ./bin/notis.js --help
+npm run docs:generate
+npm test
+```

package/bin/notis.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../src/cli.js').then(({ run }) => run());

package/config/notis_app_boundary_rules.json

@@ -0,0 +1,50 @@
+{
+  "javascript": [
+    {
+      "pattern": "window\\.__NOTIS_RUNTIME__",
+      "message": "window.__NOTIS_RUNTIME__ is forbidden; rely on the portal-injected NotisProvider runtime."
+    },
+    {
+      "pattern": "document\\.(?:body|head|documentElement)\\b",
+      "message": "document.body, document.head, and document.documentElement are forbidden; apps must stay inside the app surface."
+    },
+    {
+      "pattern": "document\\.(?:querySelector|querySelectorAll|getElementById|getElementsByClassName|getElementsByTagName)\\s*\\(\\s*(['\"`])[^\\n]*\\[data-notis-",
+      "message": "querying portal-owned [data-notis-*] hooks is forbidden."
+    },
+    {
+      "pattern": "createPortal\\s*\\(",
+      "message": "React portals are unsupported in Notis apps until a shadow-safe overlay contract exists."
+    },
+    {
+      "pattern": "@radix-ui/react-portal",
+      "message": "@radix-ui/react-portal is unsupported in Notis apps until a shadow-safe overlay contract exists."
+    },
+    {
+      "pattern": "PortalPrimitive",
+      "message": "Radix portal primitives are unsupported in Notis apps until a shadow-safe overlay contract exists."
+    }
+  ],
+  "css": [
+    {
+      "pattern": ":root\\b",
+      "message": ":root selectors are forbidden; styles must stay inside the app surface."
+    },
+    {
+      "pattern": "(^|[\\s,>+~])html(?=[\\s.#[:{>+~,]|$)",
+      "message": "html selectors are forbidden; styles must stay inside the app surface."
+    },
+    {
+      "pattern": "(^|[\\s,>+~])body(?=[\\s.#[:{>+~,]|$)",
+      "message": "body selectors are forbidden; styles must stay inside the app surface."
+    },
+    {
+      "pattern": "\\[data-notis-(?!app-root\\b)[^\\]]*\\]",
+      "message": "portal-owned [data-notis-*] selectors are forbidden. Use [data-notis-app-root] only for the app surface itself."
+    },
+    {
+      "pattern": "\\[data-sidebar(?:=[^\\]]+)?\\]",
+      "message": "portal sidebar selectors are forbidden."
+    }
+  ]
+}

package/dist/scaffolds/notis-database/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Database Changelog
+
+## [Initial Release] - {PR_MERGE_DATE}
+
+- First Store release.

package/dist/scaffolds/notis-database/app/globals.css

@@ -0,0 +1,44 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+/*
+ * The portal mounts the app inside [data-notis-app-root] (display: block,
+ * min-height: 100% from @notis/sdk/styles.css). Width 100% ensures the
+ * two-pane layout can stretch to the full content area; height stays on
+ * the SDK's min-height: 100% default so the page can grow with content.
+ * The page itself uses `h-screen` to guarantee a fixed viewport height
+ * for the two-pane divider and centered empty states.
+ */
+[data-notis-app-root] {
+  width: 100%;
+}
+
+/*
+ * Dev-preview fallback tokens. Active only when the dev entrypoint sets the
+ * data-dev-preview attribute. Production bundle runs inside the portal
+ * shadow root where the host injects real theme tokens, so this rule is
+ * scoped narrowly enough to never collide with portal-provided values.
+ */
+[data-dev-preview] {
+  --background: 0 0% 100%;
+  --foreground: 0 0% 4%;
+  --card: 0 0% 100%;
+  --card-foreground: 0 0% 4%;
+  --popover: 0 0% 100%;
+  --popover-foreground: 0 0% 4%;
+  --primary: 0 0% 9%;
+  --primary-foreground: 0 0% 98%;
+  --secondary: 240 5% 96%;
+  --secondary-foreground: 0 0% 9%;
+  --muted: 240 5% 96%;
+  --muted-foreground: 240 4% 46%;
+  --accent: 240 5% 96%;
+  --accent-foreground: 0 0% 9%;
+  --destructive: 0 84% 60%;
+  --destructive-foreground: 0 0% 98%;
+  --border: 240 6% 90%;
+  --input: 240 6% 90%;
+  --ring: 0 0% 4%;
+  --radius: 0.5rem;
+}

package/dist/scaffolds/notis-database/app/layout.tsx

@@ -0,0 +1,6 @@
+import '@notis/sdk/styles.css';
+import './globals.css';
+
+export default function AppShell({ children }: { children: React.ReactNode }) {
+  return children;
+}