@hcgstudio/ogma 0.0.0

package/dist/viewer/defaultReview.js

@@ -0,0 +1,55 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+function DashboardScreen() {
+    return (_jsxs("div", { className: "ogma-demo-screen", children: [_jsxs("aside", { className: "ogma-demo-sidebar", children: [_jsx("div", { className: "ogma-demo-brand", children: "O" }), _jsx("span", { className: "ogma-demo-nav is-active", children: "Overview" }), _jsx("span", { className: "ogma-demo-nav", children: "Signals" }), _jsx("span", { className: "ogma-demo-nav", children: "Queue" }), _jsx("span", { className: "ogma-demo-nav", children: "Settings" })] }), _jsxs("main", { className: "ogma-demo-content", children: [_jsxs("div", { className: "ogma-demo-header", children: [_jsxs("div", { children: [_jsx("p", { children: "Dashboard" }), _jsx("h2", { children: "Atlas Brief" })] }), _jsx("button", { type: "button", children: "Review ready" })] }), _jsxs("div", { className: "ogma-demo-grid", children: [_jsxs("section", { className: "ogma-demo-card is-wide", children: [_jsx("div", { className: "ogma-demo-card-title" }), _jsx("div", { className: "ogma-demo-chart", children: [42, 68, 53, 81, 61, 75, 88].map((value) => (_jsx("span", { style: { height: `${value}%` } }, value))) })] }), _jsxs("section", { className: "ogma-demo-card is-accent", children: [_jsx("strong", { children: "91%" }), _jsx("p", { children: "Review confidence" })] }), _jsxs("section", { className: "ogma-demo-card", children: [_jsx("div", { className: "ogma-demo-list-row" }), _jsx("div", { className: "ogma-demo-list-row is-medium" }), _jsx("div", { className: "ogma-demo-list-row is-short" })] }), _jsxs("section", { className: "ogma-demo-card is-action", children: [_jsx("strong", { children: "2" }), _jsx("p", { children: "Copy edits before approval" })] })] })] })] }));
+}
+function DesignSpecScreen() {
+    return (_jsxs("div", { className: "ogma-spec-screen", children: [_jsxs("header", { children: [_jsx("p", { children: "Design spec" }), _jsx("h2", { children: "Decision System" })] }), _jsx("div", { className: "ogma-spec-grid", children: ['Information density', 'Review confidence', 'Agent handoff', 'Mobile parity'].map((item, index) => (_jsxs("section", { children: [_jsx("span", { children: `0${index + 1}` }), _jsx("h3", { children: item }), _jsx("p", { children: "Prototype state prepared for pinned reviewer feedback and agent follow-up." })] }, item))) })] }));
+}
+function CheckoutFlowScreen() {
+    return (_jsxs("div", { className: "ogma-flow-screen", children: [_jsxs("header", { children: [_jsx("p", { children: "Checkout flow" }), _jsx("h2", { children: "Approve Plan" })] }), _jsx("div", { className: "ogma-flow-columns", children: ['Cart', 'Review', 'Confirm'].map((step, index) => (_jsxs("section", { children: [_jsx("span", { children: index + 1 }), _jsx("h3", { children: step }), _jsx("div", { className: "ogma-flow-line" }), _jsx("button", { type: "button", children: index === 2 ? 'Approve' : 'Continue' })] }, step))) })] }));
+}
+function MobileNavigationScreen() {
+    return (_jsx("div", { className: "ogma-mobile-screen", children: _jsxs("div", { className: "ogma-phone", children: [_jsxs("header", { children: [_jsx("span", { children: "Ogma" }), _jsx("button", { type: "button", children: "New" })] }), _jsxs("main", { children: [_jsxs("section", { children: [_jsx("p", { children: "Mobile nav" }), _jsx("h2", { children: "Design queue" })] }), _jsxs("div", { className: "ogma-phone-list", children: [_jsx("span", {}), _jsx("span", {}), _jsx("span", {})] })] }), _jsxs("nav", { children: [_jsx("span", { className: "is-active" }), _jsx("span", {}), _jsx("span", {})] })] }) }));
+}
+export function createDefaultOgmaReview() {
+    return {
+        title: 'Ogma starter review',
+        description: 'A local starter review used until an agent writes project-specific JSX screens.',
+        notes: 'Use this starter review to confirm Ogma is running, then replace it with product-specific JSX screens and product notes in designs/ogma.',
+        metadata: {
+            source: 'ogma-default',
+            updatedAt: new Date().toISOString()
+        },
+        screens: [
+            {
+                id: 'dashboard',
+                title: 'Dashboard',
+                description: 'Main review workspace for desktop inspection.',
+                component: DashboardScreen
+            },
+            {
+                id: 'design-spec',
+                title: 'Design spec',
+                description: 'Product decisions and design rationale.',
+                component: DesignSpecScreen
+            },
+            {
+                id: 'checkout-flow',
+                title: 'Checkout flow',
+                description: 'Interaction state for a step-based product path.',
+                component: CheckoutFlowScreen
+            },
+            {
+                id: 'mobile-navigation',
+                title: 'Mobile nav',
+                description: 'Compact viewport state for mobile review.',
+                component: MobileNavigationScreen,
+                width: 390
+            }
+        ]
+    };
+}
+export function MissingScreen({ screen }) {
+    return (_jsxs("div", { className: "ogma-empty-screen", children: [_jsx("h2", { children: screen.title }), _jsx("p", { children: "This screen is missing a React component export." })] }));
+}
+//# sourceMappingURL=defaultReview.js.map

package/dist/viewer/defaultReview.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaultReview.js","sourceRoot":"","sources":["../../src/viewer/defaultReview.tsx"],"names":[],"mappings":"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"}

package/dist/viewer/normalizeReviewModule.d.ts

@@ -0,0 +1,3 @@
+import type { OgmaReviewDefinition } from '../types.js';
+export declare function normalizeReviewModule(moduleValue: unknown, productNotes?: string): OgmaReviewDefinition;
+//# sourceMappingURL=normalizeReviewModule.d.ts.map

package/dist/viewer/normalizeReviewModule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizeReviewModule.d.ts","sourceRoot":"","sources":["../../src/viewer/normalizeReviewModule.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAiD,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAwDvG,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,OAAO,EAAE,YAAY,SAAK,GAAG,oBAAoB,CA6BnG"}

package/dist/viewer/normalizeReviewModule.js

@@ -0,0 +1,58 @@
+import { createDefaultOgmaReview, MissingScreen } from './defaultReview.js';
+function slugify(value, fallback) {
+    const slug = value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    return slug || fallback;
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null;
+}
+function normalizeScreen(value, index) {
+    if (!isObject(value)) {
+        return null;
+    }
+    const title = typeof value.title === 'string' ? value.title : `Screen ${index + 1}`;
+    const component = (typeof value.component === 'function'
+        ? value.component
+        : typeof value.Component === 'function'
+            ? value.Component
+            : MissingScreen);
+    return {
+        id: typeof value.id === 'string' ? slugify(value.id, `screen-${index + 1}`) : slugify(title, `screen-${index + 1}`),
+        title,
+        description: typeof value.description === 'string' ? value.description : undefined,
+        width: typeof value.width === 'number' ? value.width : undefined,
+        height: typeof value.height === 'number' ? value.height : undefined,
+        component
+    };
+}
+function pickReviewCandidate(moduleValue) {
+    return moduleValue.default ?? moduleValue.review ?? moduleValue.ogmaReview ?? moduleValue;
+}
+export function normalizeReviewModule(moduleValue, productNotes = '') {
+    const fallback = createDefaultOgmaReview();
+    if (!isObject(moduleValue)) {
+        return { ...fallback, notes: productNotes || fallback.notes };
+    }
+    const candidate = pickReviewCandidate(moduleValue);
+    if (!isObject(candidate) || !Array.isArray(candidate.screens)) {
+        return { ...fallback, notes: productNotes || fallback.notes };
+    }
+    const screens = candidate.screens
+        .map((screen, index) => normalizeScreen(screen, index))
+        .filter((screen) => screen !== null);
+    if (screens.length === 0) {
+        return { ...fallback, notes: productNotes || fallback.notes };
+    }
+    return {
+        title: typeof candidate.title === 'string' ? candidate.title : fallback.title,
+        description: typeof candidate.description === 'string' ? candidate.description : fallback.description,
+        screens,
+        notes: productNotes || (typeof candidate.notes === 'string' ? candidate.notes : fallback.notes),
+        metadata: isObject(candidate.metadata) ? candidate.metadata : fallback.metadata
+    };
+}
+//# sourceMappingURL=normalizeReviewModule.js.map

package/dist/viewer/normalizeReviewModule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizeReviewModule.js","sourceRoot":"","sources":["../../src/viewer/normalizeReviewModule.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@hcgstudio/ogma",
+  "version": "0.0.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hcgstudio/ogma.git",
+    "directory": "packages/ogma"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": "./dist/cli.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./styles.css": "./src/viewer/styles.css"
+  },
+  "files": [
+    "dist",
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
+    "dev": "yarn build && node ./dist/cli.js start --no-open",
+    "ogma": "yarn build && node ./dist/cli.js",
+    "start": "yarn build && node ./dist/cli.js start --no-open",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "lucide-react": "^1.18.0",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "vite": "^8.0.16"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "typescript": "^6.0.3"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import type { OgmaResolvedProject } from './node/project.js';
+import { DEFAULT_DESIGN_DIR, DEFAULT_SKILL_URL } from './node/templates.js';
+
+interface ParsedArgs {
+  command: string;
+  flags: Map<string, string | boolean>;
+}
+
+function parseArgs(argv: string[]): ParsedArgs {
+  const args = [...argv];
+  const command = args[0] && !args[0].startsWith('-') ? args.shift() ?? 'start' : 'start';
+  const flags = new Map<string, string | boolean>();
+
+  for (let index = 0; index < args.length; index += 1) {
+    const item = args[index];
+
+    if (!item?.startsWith('--')) {
+      continue;
+    }
+
+    const [rawName, rawValue] = item.slice(2).split('=', 2);
+    const name = rawName ?? '';
+
+    if (name.startsWith('no-')) {
+      flags.set(name.slice(3), false);
+      continue;
+    }
+
+    if (rawValue !== undefined) {
+      flags.set(name, rawValue);
+      continue;
+    }
+
+    const next = args[index + 1];
+
+    if (next && !next.startsWith('--')) {
+      flags.set(name, next);
+      index += 1;
+    } else {
+      flags.set(name, true);
+    }
+  }
+
+  return { command, flags };
+}
+
+function stringFlag(flags: Map<string, string | boolean>, name: string, fallback?: string) {
+  const value = flags.get(name);
+  return typeof value === 'string' ? value : fallback;
+}
+
+function numberFlag(flags: Map<string, string | boolean>, name: string, fallback: number) {
+  const value = Number(stringFlag(flags, name, String(fallback)));
+  return Number.isFinite(value) ? value : fallback;
+}
+
+function booleanFlag(flags: Map<string, string | boolean>, name: string, fallback: boolean) {
+  const value = flags.get(name);
+  return typeof value === 'boolean' ? value : fallback;
+}
+
+function displayPath(cwd: string, targetPath: string) {
+  const relativePath = path.relative(cwd, targetPath);
+
+  return relativePath && !relativePath.startsWith('..') && !path.isAbsolute(relativePath)
+    ? relativePath
+    : targetPath;
+}
+
+function printScaffoldResult(project: OgmaResolvedProject) {
+  console.log('Ogma scaffold ready');
+
+  if (project.createdPaths.length > 0) {
+    console.log('  Created:');
+
+    for (const createdPath of project.createdPaths) {
+      console.log(`    - ${displayPath(project.cwd, createdPath)}`);
+    }
+  } else {
+    console.log('  Created: none');
+  }
+
+  console.log(`  Designs:  ${displayPath(project.cwd, project.designEntry)}`);
+  console.log(`  Notes:    ${displayPath(project.cwd, project.notesPath)}`);
+  console.log(`  Feedback: ${displayPath(project.cwd, project.sessionPath)}`);
+}
+
+function printHelp() {
+  console.log(`Ogma local design review
+
+Usage:
+  ogma scaffold [--review designs/ogma]
+  ogma start [--review designs/ogma] [--port 4317] [--host localhost] [--no-open]
+  ogma init [--review designs/ogma]
+  ogma skill-url
+
+Commands:
+  scaffold  Create the JSX review scaffold and local Ogma data files.
+  start      Create missing design files and launch the local review server.
+  init       Alias for scaffold.
+  skill-url  Print the public Ogma skill URL.
+
+Options:
+  --review <path>     Design directory or review entry file. Default: ${DEFAULT_DESIGN_DIR}
+  --port <number>     Preferred local port. Default: 4317
+  --host <host>       Host for the local server. Default: localhost
+  --skill-url <url>   Override the URL shown to agents.
+  --open / --no-open  Open the browser after startup. Default: --open
+`);
+}
+
+async function checkRuntimeDependencies() {
+  const major = Number(process.versions.node.split('.')[0] ?? '0');
+
+  if (major < 18) {
+    throw new Error('Ogma requires Node.js 18 or newer.');
+  }
+
+  const require = createRequire(path.join(packageRoot(), 'package.json'));
+  const missing: string[] = [];
+
+  for (const specifier of ['react', 'react-dom/client', 'vite']) {
+    try {
+      require.resolve(specifier);
+    } catch {
+      missing.push(specifier);
+    }
+  }
+
+  if (missing.length > 0) {
+    throw new Error(
+      `Missing runtime dependencies: ${missing.join(', ')}. Run npm install -D @hcgstudio/ogma react react-dom vite.`
+    );
+  }
+}
+
+function packageRoot() {
+  return path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+}
+
+async function main() {
+  const { command, flags } = parseArgs(process.argv.slice(2));
+
+  if (flags.has('help') || command === 'help') {
+    printHelp();
+    return;
+  }
+
+  if (command === 'skill-url') {
+    console.log(stringFlag(flags, 'skill-url', DEFAULT_SKILL_URL));
+    return;
+  }
+
+  await checkRuntimeDependencies();
+
+  const cwd = process.cwd();
+  const review = stringFlag(flags, 'review');
+
+  if (command === 'init' || command === 'scaffold') {
+    const { ensureOgmaProject } = await import('./node/project.js');
+    const project = await ensureOgmaProject({ cwd, review });
+    printScaffoldResult(project);
+    return;
+  }
+
+  if (command !== 'start') {
+    printHelp();
+    process.exitCode = 1;
+    return;
+  }
+
+  const { startOgmaServer } = await import('./node/server.js');
+
+  await startOgmaServer({
+    cwd,
+    host: stringFlag(flags, 'host', 'localhost') ?? 'localhost',
+    open: booleanFlag(flags, 'open', true),
+    packageRoot: packageRoot(),
+    port: numberFlag(flags, 'port', 4317),
+    review,
+    skillUrl: stringFlag(flags, 'skill-url', DEFAULT_SKILL_URL)
+  });
+}
+
+main().catch((error: unknown) => {
+  console.error('');
+  console.error(`[ogma] ${error instanceof Error ? error.message : String(error)}`);
+  console.error('');
+  process.exitCode = 1;
+});

package/src/defineOgmaReview.ts

@@ -0,0 +1,5 @@
+import type { OgmaReviewDefinition } from './types.js';
+
+export function defineOgmaReview(review: OgmaReviewDefinition): OgmaReviewDefinition {
+  return review;
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+export { defineOgmaReview } from './defineOgmaReview.js';
+export { OgmaReviewApp } from './viewer/OgmaReviewApp.js';
+export { createDefaultOgmaReview } from './viewer/defaultReview.js';
+export type {
+  OgmaAnnotation,
+  OgmaAnnotationStatus,
+  OgmaClientConfig,
+  OgmaFeedbackExport,
+  OgmaPrototypeScreen,
+  OgmaPrototypeScreenProps,
+  OgmaReviewDefinition,
+  OgmaReviewMetadata,
+  OgmaReviewSession,
+  OgmaServerStatus,
+  OgmaSessionHistoryEntry,
+  OgmaViewportSnapshot
+} from './types.js';

package/src/node/project.ts

@@ -0,0 +1,143 @@
+import { mkdir, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import type { OgmaReviewSession } from '../types.js';
+import { DEFAULT_DESIGN_DIR, DEFAULT_PRODUCT_NOTES, DEFAULT_REVIEW_SOURCE } from './templates.js';
+
+export interface OgmaResolvedProject {
+  cwd: string;
+  createdPaths: string[];
+  dataDir: string;
+  defaultDesignDir: string;
+  designEntry: string;
+  existingPaths: string[];
+  feedbackPath: string;
+  historyPath: string;
+  notesPath: string;
+  sessionPath: string;
+  snapshotsDir: string;
+}
+
+const reviewEntryNames = ['review.tsx', 'review.jsx', 'ogma.review.tsx', 'ogma.review.jsx'];
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function emptySession(): OgmaReviewSession {
+  return {
+    reviewId: 'ogma-review',
+    annotations: [],
+    updatedAt: nowIso()
+  };
+}
+
+async function fileExists(filePath: string) {
+  try {
+    await stat(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function pathIsFile(filePath: string) {
+  try {
+    return (await stat(filePath)).isFile();
+  } catch {
+    return Boolean(path.extname(filePath));
+  }
+}
+
+async function ensureDirectory(dirPath: string, project: Pick<OgmaResolvedProject, 'createdPaths' | 'existingPaths'>) {
+  if (await fileExists(dirPath)) {
+    await mkdir(dirPath, { recursive: true });
+    project.existingPaths.push(dirPath);
+    return;
+  }
+
+  await mkdir(dirPath, { recursive: true });
+  project.createdPaths.push(dirPath);
+}
+
+async function ensureFile(
+  filePath: string,
+  contents: string,
+  project: Pick<OgmaResolvedProject, 'createdPaths' | 'existingPaths'>
+) {
+  if (await fileExists(filePath)) {
+    project.existingPaths.push(filePath);
+    return;
+  }
+
+  await writeFile(filePath, contents, 'utf8');
+  project.createdPaths.push(filePath);
+}
+
+async function resolveReviewTarget(cwd: string, target = DEFAULT_DESIGN_DIR) {
+  const absoluteTarget = path.resolve(cwd, target);
+
+  if (await pathIsFile(absoluteTarget)) {
+    return {
+      designDir: path.dirname(absoluteTarget),
+      designEntry: absoluteTarget
+    };
+  }
+
+  for (const entryName of reviewEntryNames) {
+    const candidate = path.join(absoluteTarget, entryName);
+
+    if (await fileExists(candidate)) {
+      return {
+        designDir: absoluteTarget,
+        designEntry: candidate
+      };
+    }
+  }
+
+  return {
+    designDir: absoluteTarget,
+    designEntry: path.join(absoluteTarget, reviewEntryNames[0] ?? 'review.tsx')
+  };
+}
+
+export async function ensureOgmaProject({
+  cwd,
+  review
+}: {
+  cwd: string;
+  review?: string;
+}): Promise<OgmaResolvedProject> {
+  const { designDir, designEntry } = await resolveReviewTarget(cwd, review);
+  const dataDir = path.join(cwd, '.ogma');
+  const notesPath = path.join(designDir, 'product-notes.md');
+  const sessionPath = path.join(dataDir, 'session.json');
+  const feedbackPath = path.join(dataDir, 'feedback.json');
+  const historyPath = path.join(dataDir, 'history.json');
+  const snapshotsDir = path.join(dataDir, 'snapshots');
+  const project = {
+    createdPaths: [],
+    existingPaths: []
+  };
+
+  await ensureDirectory(designDir, project);
+  await ensureDirectory(dataDir, project);
+  await ensureDirectory(snapshotsDir, project);
+  await ensureFile(designEntry, DEFAULT_REVIEW_SOURCE, project);
+  await ensureFile(notesPath, DEFAULT_PRODUCT_NOTES, project);
+  await ensureFile(sessionPath, `${JSON.stringify(emptySession(), null, 2)}\n`, project);
+  await ensureFile(historyPath, '[]\n', project);
+
+  return {
+    cwd,
+    createdPaths: project.createdPaths,
+    dataDir,
+    defaultDesignDir: path.relative(cwd, designDir) || '.',
+    designEntry,
+    existingPaths: project.existingPaths,
+    feedbackPath,
+    historyPath,
+    notesPath,
+    sessionPath,
+    snapshotsDir
+  };
+}