@namostack/cli 0.0.1 → 0.1.0-rc.2

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@namostack/cli",
-  "version": "0.0.1",
-  "description": "Not released yet: see https://docs.namostack.com",
-  "license": "MIT"
-}
+  "version": "0.1.0-rc.2",
+  "description": "Create, live test and publish namostack plugins.",
+  "license": "MIT",
+  "homepage": "https://docs.namostack.com",
+  "keywords": [
+    "namostack",
+    "plugin",
+    "cli"
+  ],
+  "type": "module",
+  "bin": {
+    "namostack": "./dist/index.mjs"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "!templates/*/node_modules",
+    "!templates/*/.turbo",
+    "!templates/*/dist"
+  ],
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.8.1",
+    "citty": "^0.2.2",
+    "picocolors": "^1.1.1",
+    "semver": "^7.8.5",
+    "tar": "^7.5.22",
+    "vite": "^8.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "@types/semver": "^7.8.0",
+    "tsdown": "^0.23.1",
+    "typescript": "~6.0.2",
+    "@namostack/api-client": "0.0.0",
+    "@namostack/config": "0.0.0",
+    "@namostack/types": "0.0.0",
+    "@namostack/tsconfig": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "lint": "oxlint",
+    "typecheck": "tsc -b"
+  }
+}

package/templates/react/_gitignore

@@ -0,0 +1,2 @@
+node_modules
+dist

package/templates/react/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{name}}</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/react/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "template-react",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "typecheck": "tsc"
+  },
+  "dependencies": {
+    "@fontsource-variable/inter": "^5.3.0",
+    "@fontsource-variable/source-serif-4": "^5.3.1",
+    "@juliensouki/seedui": "0.0.4",
+    "@namostack/plugin-sdk": "workspace:*",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "styled-components": "^6.1.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.7",
+    "@vitejs/plugin-react": "^6.1.1",
+    "typescript": "~6.0.2",
+    "vite": "^8.3.0"
+  }
+}

package/templates/react/public/icon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
+  <rect width="64" height="64" rx="14" fill="#6344e5" />
+  <path d="M22 16h13a11 11 0 0 1 0 22h-6v10h-7zm7 6v10h6a5 5 0 0 0 0-10z" fill="#fff" fill-rule="evenodd" />
+</svg>

package/templates/react/src/App.tsx

@@ -0,0 +1,84 @@
+import { Text } from '@juliensouki/seedui';
+import { styled } from '@juliensouki/seedui/sc';
+import { useEffect, useState } from 'react';
+import { Code, Muted } from './components/styles';
+import { Counter } from './components/Counter';
+import { Notify } from './components/Notify';
+import { describeError } from './errors';
+import { useNamostack } from './useNamostack';
+
+const Page = styled.main((props) => ({
+  maxWidth: 560,
+  margin: '0 auto',
+  padding: '40px 24px',
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 24,
+  [props.theme.breakpoints.down('sm')]: {
+    padding: '24px 16px',
+  },
+}));
+
+const Header = styled.header({
+  display: 'flex',
+  alignItems: 'center',
+  gap: 16,
+});
+
+const Icon = styled.img({
+  width: 56,
+  height: 56,
+  flexShrink: 0,
+});
+
+const Link = styled.a((props) => ({
+  color: props.theme.colors.primary.default,
+  textDecoration: 'none',
+  '&:hover': { textDecoration: 'underline' },
+}));
+
+export function App() {
+  const { context, user } = useNamostack();
+  const [displayName, setDisplayName] = useState<string>();
+  const [error, setError] = useState<string>();
+
+  useEffect(() => {
+    user
+      .getProfile()
+      .then((profile) => setDisplayName(profile.displayName))
+      .catch((caught: unknown) =>
+        setError(describeError(caught, 'user:profile:read')),
+      );
+  }, [user]);
+
+  return (
+    <Page>
+      <Header>
+        <Icon src={`${import.meta.env.BASE_URL}icon.svg`} alt="" />
+        <div>
+          <Text variant="h3">{context.name}</Text>
+          <Muted variant="p">
+            {displayName ? `Hi ${displayName}, ` : 'Hi, '}
+            this is your new plugin.
+          </Muted>
+          {error && <Muted variant="caption">{error}</Muted>}
+        </div>
+      </Header>
+
+      <Counter />
+      <Notify />
+
+      <Muted variant="caption">
+        Edit <Code>src/App.tsx</Code> and save to see it change, or{' '}
+        <Link
+          href="https://docs.namostack.com"
+          target="_blank"
+          rel="noreferrer"
+        >
+          read the docs
+        </Link>
+        .
+      </Muted>
+    </Page>
+  );
+}

package/templates/react/src/NamostackProvider.tsx

@@ -0,0 +1,41 @@
+import { ThemeProvider } from '@juliensouki/seedui';
+import { createGlobalStyle } from '@juliensouki/seedui/sc';
+import type { Namostack } from '@namostack/plugin-sdk';
+import { useEffect, useState, type ReactNode } from 'react';
+import { NamostackContext } from './useNamostack';
+
+// seedui doesn't reset the page; without this, browsers add an 8px margin.
+const GlobalStyle = createGlobalStyle`
+  body {
+    margin: 0;
+  }
+`;
+
+interface NamostackProviderProps {
+  namostack: Namostack;
+  children: ReactNode;
+}
+
+/** Shares the connection with every component, and follows the app's theme. */
+export function NamostackProvider({
+  namostack,
+  children,
+}: NamostackProviderProps) {
+  const [mode, setMode] = useState(namostack.context.theme.mode);
+
+  useEffect(
+    () => namostack.onThemeChange((theme) => setMode(theme.mode)),
+    [namostack],
+  );
+
+  useEffect(() => {
+    document.documentElement.style.colorScheme = mode;
+  }, [mode]);
+
+  return (
+    <NamostackContext.Provider value={namostack}>
+      <GlobalStyle />
+      <ThemeProvider mode={mode}>{children}</ThemeProvider>
+    </NamostackContext.Provider>
+  );
+}

package/templates/react/src/components/Counter.tsx

@@ -0,0 +1,101 @@
+import { Button, Text } from '@juliensouki/seedui';
+import type { StoredDocument } from '@namostack/plugin-sdk';
+import { useEffect, useState } from 'react';
+import { describeError } from '../errors';
+import { useNamostack } from '../useNamostack';
+import { ExampleCard } from './ExampleCard';
+import { Actions, Code } from './styles';
+
+interface Clicks {
+  count: number;
+}
+
+type Action = 'increment' | 'reset';
+
+/** A counter saved for the current user: it survives reloads and devices. */
+export function Counter() {
+  const { data } = useNamostack();
+  const [clicks, setClicks] = useState<StoredDocument<Clicks> | null>();
+  const [pending, setPending] = useState<Action>();
+  const [error, setError] = useState<string>();
+
+  useEffect(() => {
+    data
+      .find<Clicks>('clicks', { limit: 1 })
+      .then(({ items }) => setClicks(items[0] ?? null))
+      .catch((caught: unknown) => {
+        setClicks(null);
+        setError(describeError(caught, 'storage'));
+      });
+  }, [data]);
+
+  const run = async (
+    action: Action,
+    change: () => Promise<StoredDocument<Clicks> | null>,
+  ) => {
+    setPending(action);
+    setError(undefined);
+
+    try {
+      setClicks(await change());
+    } catch (caught) {
+      setError(describeError(caught, 'storage'));
+    } finally {
+      setPending(undefined);
+    }
+  };
+
+  const increment = () =>
+    run('increment', () =>
+      clicks
+        ? data.update<Clicks>('clicks', clicks.id, { count: clicks.count + 1 })
+        : data.insert<Clicks>('clicks', { count: 1 }),
+    );
+
+  const reset = () =>
+    run('reset', async () => {
+      if (clicks) {
+        await data.delete('clicks', clicks.id);
+      }
+
+      return null;
+    });
+
+  const loading = clicks === undefined;
+
+  return (
+    <ExampleCard
+      title="Save data"
+      permission="storage"
+      error={error}
+      description={
+        <>
+          Each click is saved with <Code>data.update</Code>: reload, the count
+          stays.
+        </>
+      }
+    >
+      <Text variant="h2">{clicks?.count ?? 0}</Text>
+      <Actions>
+        <Button
+          size="md"
+          isLoading={pending === 'increment'}
+          disabled={loading || pending === 'reset'}
+          onClick={increment}
+        >
+          Click me
+        </Button>
+        <Button
+          size="md"
+          color="neutral"
+          variant="transparent"
+          isLoading={pending === 'reset'}
+          disabled={!clicks || pending === 'increment'}
+          onClick={reset}
+        >
+          Reset
+        </Button>
+      </Actions>
+    </ExampleCard>
+  );
+}

package/templates/react/src/components/ExampleCard.tsx

@@ -0,0 +1,55 @@
+import { Card, Tag, Text } from '@juliensouki/seedui';
+import { styled } from '@juliensouki/seedui/sc';
+import type { ReactNode } from 'react';
+import { Muted } from './styles';
+
+const Root = styled(Card)({
+  width: '100%',
+  boxSizing: 'border-box',
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 16,
+});
+
+const Heading = styled.div({
+  display: 'flex',
+  alignItems: 'center',
+  justifyContent: 'space-between',
+  gap: 8,
+});
+
+const ErrorText = styled(Text)((props) => ({
+  color: props.theme.colors.error.default,
+}));
+
+interface ExampleCardProps {
+  title: string;
+  description: ReactNode;
+  /** The manifest permission the example needs. */
+  permission: string;
+  error?: string;
+  children: ReactNode;
+}
+
+/** One SDK feature: what it does, the permission it needs, and a way to try it. */
+export function ExampleCard({
+  title,
+  description,
+  permission,
+  error,
+  children,
+}: ExampleCardProps) {
+  return (
+    <Root variant="outlined" padding={20}>
+      <Heading>
+        <Text variant="h5">{title}</Text>
+        <Tag color="neutral" size="sm">
+          {permission}
+        </Tag>
+      </Heading>
+      <Muted variant="p">{description}</Muted>
+      {children}
+      {error && <ErrorText variant="caption">{error}</ErrorText>}
+    </Root>
+  );
+}

package/templates/react/src/components/Notify.tsx

@@ -0,0 +1,41 @@
+import { Button } from '@juliensouki/seedui';
+import { useState } from 'react';
+import { describeError } from '../errors';
+import { useNamostack } from '../useNamostack';
+import { ExampleCard } from './ExampleCard';
+import { Actions, Code } from './styles';
+
+/** Shows a toast in the app, outside the plugin's frame. */
+export function Notify() {
+  const { ui } = useNamostack();
+  const [error, setError] = useState<string>();
+
+  const notify = async () => {
+    setError(undefined);
+
+    try {
+      await ui.notify({ message: 'Hello from your plugin!', tone: 'success' });
+    } catch (caught) {
+      setError(describeError(caught, 'ui:notify'));
+    }
+  };
+
+  return (
+    <ExampleCard
+      title="Talk to the app"
+      permission="ui:notify"
+      error={error}
+      description={
+        <>
+          <Code>ui.notify</Code> shows a notification in the app.
+        </>
+      }
+    >
+      <Actions>
+        <Button size="md" color="neutral" onClick={notify}>
+          Say hello
+        </Button>
+      </Actions>
+    </ExampleCard>
+  );
+}

package/templates/react/src/components/styles.ts

@@ -0,0 +1,24 @@
+import { Text } from '@juliensouki/seedui';
+import { styled } from '@juliensouki/seedui/sc';
+
+export const Actions = styled.div({
+  display: 'flex',
+  flexWrap: 'wrap',
+  gap: 8,
+});
+
+export const Code = styled.code((props) => ({
+  padding: '1px 6px',
+  borderRadius: props.theme.borderRadius(1),
+  background:
+    props.theme.colors.neutral[props.theme.mode === 'light' ? 200 : 400],
+  fontFamily: 'ui-monospace, SFMono-Regular, Menlo, Consolas, monospace',
+  fontSize: '0.875em',
+}));
+
+export const Muted = styled(Text)((props) => ({
+  color:
+    props.theme.mode === 'light'
+      ? props.theme.colors.neutral[600]
+      : props.theme.colors.neutral[900],
+}));

package/templates/react/src/errors.ts

@@ -0,0 +1,10 @@
+import { BridgeError } from '@namostack/plugin-sdk';
+
+/** What to show when an SDK call fails; a missing permission says how to add it. */
+export function describeError(error: unknown, permission: string): string {
+  if (error instanceof BridgeError && error.code === 'permission_denied') {
+    return `Add "${permission}" to the permissions in namostack.plugin.json.`;
+  }
+
+  return error instanceof BridgeError ? error.message : String(error);
+}

package/templates/react/src/main.tsx

@@ -0,0 +1,20 @@
+import { connect } from '@namostack/plugin-sdk';
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { App } from './App';
+import { NamostackProvider } from './NamostackProvider';
+
+// seedui's fonts, as in the namostack app.
+import '@fontsource-variable/inter';
+import '@fontsource-variable/source-serif-4';
+
+// Plugins only run inside the namostack app: anywhere else, this throws.
+const namostack = await connect();
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <NamostackProvider namostack={namostack}>
+      <App />
+    </NamostackProvider>
+  </StrictMode>,
+);

package/templates/react/src/useNamostack.ts

@@ -0,0 +1,16 @@
+import type { Namostack } from '@namostack/plugin-sdk';
+import { createContext, useContext } from 'react';
+
+/** Provided by `NamostackProvider`. */
+export const NamostackContext = createContext<Namostack | undefined>(undefined);
+
+/** The data, user and UI methods of the namostack app. */
+export function useNamostack(): Namostack {
+  const namostack = useContext(NamostackContext);
+
+  if (!namostack) {
+    throw new Error('useNamostack is only usable inside NamostackProvider.');
+  }
+
+  return namostack;
+}

package/templates/react/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "es2023",
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "jsx": "react-jsx",
+    "types": ["vite/client"],
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src", "vite.config.ts"]
+}

package/templates/react/vite.config.ts

@@ -0,0 +1,7 @@
+import { namostackPlugin } from '@namostack/plugin-sdk/vite';
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [react(), namostackPlugin()],
+});

package/templates/vanilla/_gitignore

@@ -0,0 +1,2 @@
+node_modules
+dist

package/templates/vanilla/index.html

@@ -0,0 +1,61 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{name}}</title>
+  </head>
+  <body>
+    <main class="page" hidden>
+      <header class="header">
+        <img class="icon" src="./icon.svg" alt="" />
+        <div>
+          <h1 class="h3" id="name"></h1>
+          <p class="p muted" id="greeting">Hi, this is your new plugin.</p>
+          <p class="caption muted" id="greeting-error" hidden></p>
+        </div>
+      </header>
+
+      <section class="card">
+        <div class="card-heading">
+          <h2 class="h5">Save data</h2>
+          <span class="tag">storage</span>
+        </div>
+        <p class="p muted">
+          Each click is saved with <code>data.update</code>: reload, the count
+          stays.
+        </p>
+        <p class="h2" id="count">0</p>
+        <div class="actions">
+          <button class="button" id="increment" disabled>Click me</button>
+          <button class="button button-transparent" id="reset" disabled>
+            Reset
+          </button>
+        </div>
+        <p class="caption error" id="count-error" hidden></p>
+      </section>
+
+      <section class="card">
+        <div class="card-heading">
+          <h2 class="h5">Talk to the app</h2>
+          <span class="tag">ui:notify</span>
+        </div>
+        <p class="p muted">
+          <code>ui.notify</code> shows a notification in the app.
+        </p>
+        <div class="actions">
+          <button class="button button-neutral" id="notify">Say hello</button>
+        </div>
+        <p class="caption error" id="notify-error" hidden></p>
+      </section>
+
+      <p class="caption muted">
+        Edit <code>src/main.ts</code> and save to see it change, or
+        <a href="https://docs.namostack.com" target="_blank" rel="noreferrer"
+          >read the docs</a
+        >.
+      </p>
+    </main>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/templates/vanilla/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "template-vanilla",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "typecheck": "tsc"
+  },
+  "dependencies": {
+    "@fontsource-variable/inter": "^5.3.0",
+    "@fontsource-variable/source-serif-4": "^5.3.1",
+    "@namostack/plugin-sdk": "workspace:*"
+  },
+  "devDependencies": {
+    "typescript": "~6.0.2",
+    "vite": "^8.3.0"
+  }
+}

package/templates/vanilla/public/icon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
+  <rect width="64" height="64" rx="14" fill="#6344e5" />
+  <path d="M22 16h13a11 11 0 0 1 0 22h-6v10h-7zm7 6v10h6a5 5 0 0 0 0-10z" fill="#fff" fill-rule="evenodd" />
+</svg>