@tuongaz/seeflow 0.1.61 → 0.1.64

package/src/schema.ts

@@ -8,8 +8,8 @@ const PositionSchema = z.object({
 // US-008: HttpAction was the original shape for both playAction and resetAction
 // in pre-script-action releases. After US-001 cut playAction to script-only and
 // US-008 cut resetAction the same way, no schema in this file uses HttpAction
-// anymore. Connectors keep the `http` *kind literal* for visual semantics, but
-// that's an independent enum — search before re-adding any HttpActionSchema.
+// anymore. `HttpMethodSchema` is still used for the optional `method` field on
+// connectors (documentation metadata).
 const HttpMethodSchema = z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
 
 // Curated palette tokens. Stored on disk as readable names; the frontend maps
@@ -62,10 +62,12 @@ const isCleanRelativePath = (s: string): boolean => {
 };
 
 // Script-based action: the studio spawns `<interpreter> [...args] <scriptPath>`
-// from the project's repoPath. `scriptPath` is a relative path under
-// `<project>/.seeflow/`; `args` (optional) prepend to the interpreter; `input`
-// (optional) gets JSON-serialized and written to the child's stdin then closed;
-// `timeoutMs` caps execution (default applied at the spawn layer, not here).
+// from the project's repoPath. `scriptPath` is a relative path under the
+// project root (typically `nodes/<id>/scripts/<name>` for play/status, or any
+// project-root-relative path for reset); `args` (optional) prepend to the
+// interpreter; `input` (optional) gets JSON-serialized and written to the
+// child's stdin then closed; `timeoutMs` caps execution (default applied at
+// the spawn layer, not here).
 const ScriptActionSchema = z.object({
   kind: z.literal('script'),
   interpreter: z.string().min(1),
@@ -117,7 +119,6 @@ export const StateSourceSchema = z.discriminatedUnion('kind', [
 
 const NodeDataBaseSchema = z.object({
   name: z.string().min(1),
-  kind: z.string().min(1),
   stateSource: StateSourceSchema,
   // Reserved for v2: a module path resolved by future skills runtime.
   // Schema-only at v1 — never read at runtime.
@@ -188,14 +189,14 @@ const ShapeNodeSchema = z.object({
   data: ShapeNodeDataSchema,
 });
 
-// Decorative image node — references a file under `<project>/.seeflow/` by
+// Decorative image node — references a file under the project root by
 // relative path (US-004 hard-cut from base64 data URLs to path-backed files).
-// `path` is a relative path under `<project>/.seeflow/` for imageNode uploads: rooted
-// at `.seeflow/`, no leading slash, no `..` segments. The renderer fetches via
+// `path` is a relative path under the project root for imageNode uploads:
+// no leading slash, no `..` segments. The renderer fetches via
 // `GET /api/projects/:id/files/:path`.
 const ImageNodeDataSchema = z.object({
   path: z.string().min(1).refine(isCleanRelativePath, {
-    message: 'path must be a relative path under .seeflow/ (no absolute / traversal)',
+    message: 'path must be a relative path under the project root (no absolute / traversal)',
   }),
   alt: z.string().optional(),
   ...NodeVisualBaseShape,
@@ -212,8 +213,8 @@ const ImageNodeSchema = z.object({
 // US-011 (illustrative-shapes-htmlnode): htmlNode is the escape-hatch node type
 // for content the curated nodes don't cover — carries author-written HTML
 // inline via `data.html`. The studio externalizes the content to
-// `<project>/.seeflow/nodes/<id>/view.html` and stores a `file://` ref in
-// flow.json; the resolver inlines the content back on read so consumers see
+// `<project>/nodes/<id>/view.html` and stores a `file://` ref in flow.json;
+// the resolver inlines the content back on read so consumers see
 // the resolved HTML string. The renderer sanitizes before injection
 // (US-013/US-014). Spreads NodeVisualBaseShape so authors can theme the
 // wrapper (border / background / radius / font) with the same fields
@@ -273,17 +274,13 @@ const NodeSchema = z.discriminatedUnion('type', [
   HtmlNodeSchema,
 ]);
 
-// Connector is the semantic edge between two nodes — describes HOW they are
-// connected, not just THAT they are. Discriminated on `kind`:
-//   • http    — service-to-service HTTP call (method + url echo of the playAction)
-//   • event   — pub/sub event (eventName)
-//   • queue   — message-queue handoff (queueName)
-//   • default — user-drawn, no semantic payload (UI annotation only)
-// The frontend derives a React Flow Edge from each connector at render time
-// (id/source/target are reused; `label` becomes the edge label; visual style
-// is picked from `kind`, but per-connector `style`/`color` overrides it). v1
-// has no separate `edges[]` array — connectors are the sole source of truth
-// for inter-node connections.
+// Connector is the edge between two nodes. The frontend derives a React Flow
+// Edge from each connector at render time (id/source/target are reused;
+// `label` becomes the edge label; visual style comes from optional
+// `style`/`color` fields). v1 has no separate `edges[]` array — connectors
+// are the sole source of truth for inter-node connections. Optional
+// metadata fields (`method`/`url`/`eventName`/`queueName`) may be present
+// for documentation purposes; the renderer does not branch on them.
 const ConnectorStyleSchema = z.enum(['solid', 'dashed', 'dotted']);
 const ConnectorDirectionSchema = z.enum(['forward', 'backward', 'both', 'none']);
 // Path geometry — orthogonal to `style` (which means the dash pattern). Absent
@@ -291,7 +288,7 @@ const ConnectorDirectionSchema = z.enum(['forward', 'backward', 'both', 'none'])
 // (right-angle / zigzag) path. (US-017)
 const ConnectorPathSchema = z.enum(['curve', 'step']);
 
-// Visual fields shared by every connector kind. All optional — existing
+// Visual fields shared by every connector. All optional — existing
 // demo files predate them and must continue to parse. `direction` defaults
 // to 'forward' when absent (the historical behavior).
 const ConnectorVisualBaseShape = {
@@ -305,7 +302,7 @@ const ConnectorVisualBaseShape = {
   fontSize: z.number().positive().optional(),
 };
 
-// Handle ids — every node kind in this codebase uses the same four-handle
+// Handle ids — every node type in this codebase uses the same four-handle
 // layout: target-only on top + left, source-only on right + bottom (US-013).
 // `sourceHandle` MUST be a source-side id and `targetHandle` MUST be a
 // target-side id; sending the wrong role leaves a stranded endpoint at render
@@ -350,37 +347,14 @@ const ConnectorBaseShape = {
   ...ConnectorVisualBaseShape,
 };
 
-const HttpConnectorSchema = z.object({
+const ConnectorSchema = z.object({
   ...ConnectorBaseShape,
-  kind: z.literal('http'),
   method: HttpMethodSchema.optional(),
   url: z.string().min(1).optional(),
+  eventName: z.string().min(1).optional(),
+  queueName: z.string().min(1).optional(),
 });
 
-const EventConnectorSchema = z.object({
-  ...ConnectorBaseShape,
-  kind: z.literal('event'),
-  eventName: z.string().min(1),
-});
-
-const QueueConnectorSchema = z.object({
-  ...ConnectorBaseShape,
-  kind: z.literal('queue'),
-  queueName: z.string().min(1),
-});
-
-const DefaultConnectorSchema = z.object({
-  ...ConnectorBaseShape,
-  kind: z.literal('default'),
-});
-
-const ConnectorSchema = z.discriminatedUnion('kind', [
-  HttpConnectorSchema,
-  EventConnectorSchema,
-  QueueConnectorSchema,
-  DefaultConnectorSchema,
-]);
-
 export const ResolvedFlowSchema = z
   .object({
     version: z.literal(2),
@@ -439,10 +413,6 @@ export type HtmlNodeData = z.infer<typeof HtmlNodeDataSchema>;
 export type ShapeKind = z.infer<typeof ShapeKindSchema>;
 export type ColorToken = z.infer<typeof ColorTokenSchema>;
 export type Connector = z.infer<typeof ConnectorSchema>;
-export type HttpConnector = z.infer<typeof HttpConnectorSchema>;
-export type EventConnector = z.infer<typeof EventConnectorSchema>;
-export type QueueConnector = z.infer<typeof QueueConnectorSchema>;
-export type DefaultConnector = z.infer<typeof DefaultConnectorSchema>;
 export type ConnectorStyle = z.infer<typeof ConnectorStyleSchema>;
 export type ConnectorDirection = z.infer<typeof ConnectorDirectionSchema>;
 export type ConnectorPath = z.infer<typeof ConnectorPathSchema>;
@@ -456,12 +426,11 @@ export type StateSource = z.infer<typeof StateSourceSchema>;
 
 // =============================================================================
 // Flow schema — pure semantic data, every visual/layout field stripped.
-// What lives on disk in <project>/.seeflow/flow.json after the split.
+// What lives on disk in <project>/flow.json after the split.
 // =============================================================================
 
 const FlowNodeDataBaseShape = {
   name: z.string().min(1),
-  kind: z.string().min(1),
   stateSource: StateSourceSchema,
   handlerModule: z.string().optional(),
   icon: z.string().optional(),
@@ -495,7 +464,7 @@ const FlowShapeNodeDataSchema = z
 const FlowImageNodeDataSchema = z
   .object({
     path: z.string().min(1).refine(isCleanRelativePath, {
-      message: 'path must be a relative path under .seeflow/ (no absolute / traversal)',
+      message: 'path must be a relative path under the project root (no absolute / traversal)',
     }),
     alt: z.string().optional(),
     ...NodeDescriptionBaseShape,
@@ -588,45 +557,16 @@ const FlowConnectorBaseShape = {
   label: z.string().optional(),
 };
 
-export const FlowHttpConnectorSchema = z
+export const FlowConnectorSchema = z
   .object({
     ...FlowConnectorBaseShape,
-    kind: z.literal('http'),
     method: HttpMethodSchema.optional(),
     url: z.string().min(1).optional(),
+    eventName: z.string().min(1).optional(),
+    queueName: z.string().min(1).optional(),
   })
   .strict();
 
-export const FlowEventConnectorSchema = z
-  .object({
-    ...FlowConnectorBaseShape,
-    kind: z.literal('event'),
-    eventName: z.string().min(1),
-  })
-  .strict();
-
-export const FlowQueueConnectorSchema = z
-  .object({
-    ...FlowConnectorBaseShape,
-    kind: z.literal('queue'),
-    queueName: z.string().min(1),
-  })
-  .strict();
-
-export const FlowDefaultConnectorSchema = z
-  .object({
-    ...FlowConnectorBaseShape,
-    kind: z.literal('default'),
-  })
-  .strict();
-
-const FlowConnectorSchema = z.discriminatedUnion('kind', [
-  FlowHttpConnectorSchema,
-  FlowEventConnectorSchema,
-  FlowQueueConnectorSchema,
-  FlowDefaultConnectorSchema,
-]);
-
 export const FlowSchema = z
   .object({
     version: z.literal(2),
@@ -663,10 +603,10 @@ export type FlowConnector = z.infer<typeof FlowConnectorSchema>;
 
 // Envelope-only flow shape for the `seeflow schema flow` surface. The full
 // FlowSchema validates the whole graph; this companion schema describes the
-// top-level shape without inlining every node + connector variant, so the
-// runtime-introspectable JSON Schema stays compact. Authors drill into
-// `seeflow schema node` / `seeflow schema connector` for the per-variant
-// shapes. Not used for validation — only the catalog reads it.
+// top-level shape without inlining every node variant or the connector
+// shape, so the runtime-introspectable JSON Schema stays compact. Authors
+// drill into `seeflow schema node` / `seeflow schema connector` for the
+// detailed shapes. Not used for validation — only the catalog reads it.
 export const FlowEnvelopeSchema = z
   .object({
     version: z.literal(2),
@@ -680,7 +620,7 @@ export const FlowEnvelopeSchema = z
 
 // =============================================================================
 // Style schema — keyed map of presentation overrides, side-table by id.
-// What lives on disk in <project>/.seeflow/style.json (optional file).
+// What lives on disk in <project>/style.json (optional file).
 // =============================================================================
 
 const NodeStyleSchema = z

package/src/server.ts

@@ -54,8 +54,6 @@ export interface CreateAppOptions {
   /** Inject a ProxyFacade — tests use this to short-circuit runPlay /
    *  runReset / stopAllPlays and assert call order. */
   proxy?: ProxyFacade;
-  /** Override base directory for new projects. Defaults to ~/.seeflow. Tests inject a tmp dir. */
-  projectBaseDir?: string;
 }
 
 const DEFAULT_VITE_DEV_URL = 'http://localhost:5173';
@@ -139,7 +137,6 @@ export function createApp(options: CreateAppOptions = {}): Hono {
       statusRunner,
       processSpawner: options.processSpawner,
       proxy: options.proxy,
-      projectBaseDir: options.projectBaseDir,
     }),
   );
 
@@ -158,7 +155,6 @@ export function createApp(options: CreateAppOptions = {}): Hono {
     const mcpServer = createMcpServer({
       registry,
       watcher,
-      projectBaseDir: options.projectBaseDir,
     });
     await mcpServer.connect(transport);
     try {

package/src/short-id.ts

@@ -22,3 +22,27 @@ export function shortId(len = 10): string {
   }
   return out;
 }
+
+// Public id-type vocabulary shared by the CLI (`seeflow ids`), the REST API
+// (`GET /api/ids/:type/:count`), and the MCP tool (`seeflow_ids`). Internal
+// prefix `conn-` stays canonical (operations.ts mints connectors as
+// `conn-…`); the friendlier word `connector` is what callers pass.
+export const ID_TYPES = ['node', 'connector'] as const;
+export type IdType = (typeof ID_TYPES)[number];
+
+export const ID_PREFIX_BY_TYPE: Record<IdType, string> = {
+  node: 'node-',
+  connector: 'conn-',
+};
+
+export const MAX_ID_COUNT = 100;
+
+export const isIdType = (v: unknown): v is IdType =>
+  typeof v === 'string' && (ID_TYPES as readonly string[]).includes(v);
+
+export function generateIds(type: IdType, count: number): string[] {
+  const prefix = ID_PREFIX_BY_TYPE[type];
+  const out: string[] = new Array(count);
+  for (let i = 0; i < count; i++) out[i] = `${prefix}${shortId()}`;
+  return out;
+}

package/src/status-runner.ts

@@ -16,8 +16,8 @@
  * report. A solicited kill (restart / stop / maxLifetimeMs) is silent on exit.
  *
  * Defense-in-depth on scriptPath mirrors proxy.ts:`resolveScript` — realpath
- * the resolved file against `<repoPath>/.seeflow/nodes/<nodeId>/` so a
- * symlink-escape can't spawn arbitrary scripts outside the node folder.
+ * the resolved file against `<repoPath>/nodes/<nodeId>/` so a symlink-escape
+ * can't spawn arbitrary scripts outside the node folder.
  */
 
 import { existsSync, realpathSync } from 'node:fs';
@@ -63,7 +63,7 @@ interface TrackedHandle {
 type ResolvedScript = { ok: true; absPath: string } | { ok: false };
 
 function resolveScript(repoPath: string, nodeId: string, scriptPath: string): ResolvedScript {
-  const nodeRoot = join(repoPath, '.seeflow', 'nodes', nodeId);
+  const nodeRoot = join(repoPath, 'nodes', nodeId);
   let realRoot: string;
   try {
     realRoot = realpathSync(nodeRoot);

package/src/watcher.ts

@@ -1,6 +1,10 @@
 import { createHash } from 'node:crypto';
 import { type FSWatcher, existsSync, readFileSync, statSync, watch } from 'node:fs';
 import { basename, dirname, isAbsolute, join } from 'node:path';
+// `file://` refs in flow.json resolve against the project root (the dir that
+// contains flow.json). The studio is path-agnostic — whatever path the caller
+// supplied is the project root.
+const projectRootForFlow = (flowPath: string): string => dirname(flowPath);
 import type { EventBus } from './events.ts';
 import { resolveFileRefs } from './file-ref.ts';
 import { mergeFlowAndStyle } from './merge.ts';
@@ -70,17 +74,17 @@ export interface FlowWatcher {
     styleContent: string,
   ): void;
   /**
-   * Relative paths (under `<project>/.seeflow/`) currently being watched
-   * because they're referenced by a node's `data.path` (imageNode). htmlNode
-   * content rides on the file:// resolver via `data.html`, not this list.
-   * Sorted for stable assertion order. Used by tests.
+   * Relative paths (under the project root) currently being watched because
+   * they're referenced by a node's `data.path` (imageNode). htmlNode content
+   * rides on the file:// resolver via `data.html`, not this list. Sorted for
+   * stable assertion order. Used by tests.
    */
   referencedPaths(flowId: string): string[];
 }
 
 interface FileWatchEntry {
   fsWatcher: FSWatcher;
-  /** basename → relative path (rooted at `<project>/.seeflow/`) */
+  /** basename → relative path (rooted at the project root) */
   files: Map<string, string>;
   /** basename → pending debounce timer for the next broadcast */
   timers: Map<string, ReturnType<typeof setTimeout>>;
@@ -101,22 +105,6 @@ interface WatchHandle {
 const resolveFilePath = (repoPath: string, flowPath: string): string =>
   isAbsolute(flowPath) ? flowPath : join(repoPath, flowPath);
 
-// `file://` refs in flow.json resolve against `<project>/.seeflow/` per the
-// skill spec — not against the flow file's own directory. Walk up from the
-// flow's parent looking for an ancestor named `.seeflow`. Fallback to the
-// flow's parent for flows registered outside the `.seeflow/` convention.
-const computeSeeflowRoot = (flowPath: string): string => {
-  const flowDir = dirname(flowPath);
-  let current = flowDir;
-  while (true) {
-    if (basename(current) === '.seeflow') return current;
-    const parent = dirname(current);
-    if (parent === current) break;
-    current = parent;
-  }
-  return flowDir;
-};
-
 const isCleanRelativePath = (p: string): boolean => {
   if (!p) return false;
   // Reject data URLs early — the pre-launch hard-cut (US-004) replaces
@@ -162,7 +150,7 @@ export interface ReadMergedFlowResult {
   flow: ResolvedFlow | null;
   valid: boolean;
   error: string | null;
-  /** Sorted relative paths under `<seeflowRoot>` resolved via file://. */
+  /** Sorted relative paths under the project root resolved via file://. */
   fileRefs: string[];
   /** Flow file paths referenced via imageNode.path. */
   staticRefs: string[];
@@ -181,7 +169,7 @@ export function readMergedFlow(flowPath: string): ReadMergedFlowResult {
   }
 
   const flowDir = dirname(flowPath);
-  const seeflowRoot = computeSeeflowRoot(flowPath);
+  const projectRoot = projectRootForFlow(flowPath);
   const stylePath = join(flowDir, 'style.json');
 
   let rawFlow: unknown;
@@ -194,7 +182,7 @@ export function readMergedFlow(flowPath: string): ReadMergedFlowResult {
     };
   }
 
-  const { resolved, refs } = resolveFileRefs(rawFlow, seeflowRoot);
+  const { resolved, refs } = resolveFileRefs(rawFlow, projectRoot);
   const staticRefs = collectReferencedPaths(rawFlow);
 
   const flowParse = FlowSchema.safeParse(resolved);
@@ -306,12 +294,12 @@ export function createWatcher(deps: WatcherDeps): FlowWatcher {
   const reconcileFileWatchers = (
     flowId: string,
     handle: WatchHandle,
-    seeflowRoot: string,
+    projectRoot: string,
     refs: string[],
   ): void => {
     const desired = new Map<string, Map<string, string>>();
     for (const relPath of refs) {
-      const abs = join(seeflowRoot, relPath);
+      const abs = join(projectRoot, relPath);
       const dir = dirname(abs);
       const base = basename(abs);
       let dirMap = desired.get(dir);
@@ -417,7 +405,7 @@ export function createWatcher(deps: WatcherDeps): FlowWatcher {
     const handle = handles.get(flowId);
     if (handle) {
       const allRefs = [...result.fileRefs, ...result.staticRefs];
-      reconcileFileWatchers(flowId, handle, computeSeeflowRoot(filePath), allRefs);
+      reconcileFileWatchers(flowId, handle, projectRootForFlow(filePath), allRefs);
     }
 
     return next;

package/src/sdk-template.ts

@@ -1,37 +0,0 @@
-/**
- * Self-contained `emit()` helper copied verbatim into a target repo's
- * `.seeflow/sdk/emit.ts` by `seeflow register` when the demo declares any
- * event-bound state node. Kept dependency-free so the user's app can call it
- * without installing `@seeflow/sdk`.
- */
-export const EMIT_TEMPLATE = `// Auto-generated by seeflow register. Safe to commit; safe to delete.
-// Re-running register will not overwrite this file.
-export type EmitStatus = 'running' | 'done' | 'error';
-
-export interface EmitOptions {
-  runId?: string;
-  payload?: unknown;
-  studioUrl?: string;
-}
-
-const readEnv = (key: string): string | undefined => {
-  const proc = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process;
-  return proc?.env?.[key];
-};
-
-export async function emit(
-  flowId: string,
-  nodeId: string,
-  status: EmitStatus,
-  opts: EmitOptions = {},
-): Promise<void> {
-  const base = (
-    opts.studioUrl ?? readEnv('SEEFLOW_STUDIO_URL') ?? 'http://localhost:4321'
-  ).replace(/\\/+$/, '');
-  await fetch(\`\${base}/api/emit\`, {
-    method: 'POST',
-    headers: { 'content-type': 'application/json' },
-    body: JSON.stringify({ flowId, nodeId, status, runId: opts.runId, payload: opts.payload }),
-  });
-}
-`;

package/src/sdk-writer.ts

@@ -1,37 +0,0 @@
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import type { Flow } from './schema.ts';
-import { EMIT_TEMPLATE } from './sdk-template.ts';
-
-export type SdkWriteOutcome = 'skipped' | 'written' | 'present';
-
-export interface SdkWriteResult {
-  outcome: SdkWriteOutcome;
-  /** Absolute path of the SDK file (written or pre-existing). Null on `skipped`. */
-  filePath: string | null;
-}
-
-/**
- * Writes `.seeflow/sdk/emit.ts` into a target repo iff the demo declares any
- * node with `stateSource.kind === 'event'`. Idempotent: existing files are
- * never overwritten. The only place M1's CLI mutates a user repo.
- */
-export function writeSdkEmitIfNeeded(repoPath: string, demo: Flow): SdkWriteResult {
-  const hasEventState = demo.nodes.some(
-    (n) =>
-      n.type !== 'shapeNode' &&
-      n.type !== 'imageNode' &&
-      n.type !== 'iconNode' &&
-      n.type !== 'htmlNode' &&
-      n.data.stateSource.kind === 'event',
-  );
-  if (!hasEventState) return { outcome: 'skipped', filePath: null };
-
-  const sdkDir = join(repoPath, '.seeflow', 'sdk');
-  const filePath = join(sdkDir, 'emit.ts');
-  if (existsSync(filePath)) return { outcome: 'present', filePath };
-
-  mkdirSync(sdkDir, { recursive: true });
-  writeFileSync(filePath, EMIT_TEMPLATE);
-  return { outcome: 'written', filePath };
-}