@hasna/workflows 0.1.0

package/dist/serve/index.js

@@ -0,0 +1,232 @@
+#!/usr/bin/env bun
+// @bun
+
+// src/service.ts
+import { join } from "path";
+// package.json
+var package_default = {
+  name: "@hasna/workflows",
+  version: "0.1.0",
+  description: "Universal graph workflow app \u2014 scaffold with version/health/readiness on all four surfaces; graph language, store, session WAL, daemon, and lane adapters are roadmap",
+  type: "module",
+  main: "./dist/index.js",
+  types: "./types/index.d.ts",
+  bin: {
+    workflows: "dist/cli/index.js",
+    "workflows-mcp": "dist/mcp/index.js",
+    "workflows-serve": "dist/serve/index.js"
+  },
+  exports: {
+    ".": {
+      types: "./types/index.d.ts",
+      import: "./dist/index.js"
+    },
+    "./sdk": {
+      types: "./types/index.d.ts",
+      import: "./dist/index.js"
+    },
+    "./cli": {
+      types: "./types/cli/index.d.ts",
+      import: "./dist/cli/index.js"
+    }
+  },
+  files: [
+    "dist",
+    "types",
+    "README.md",
+    "LICENSE",
+    "hasna.contract.json"
+  ],
+  scripts: {
+    build: "bun run build:runtime && bun run build:types",
+    "build:runtime": "rm -rf dist && bun build src/cli/index.ts --outdir dist/cli --target bun --packages external && bun build src/mcp/index.ts --outdir dist/mcp --target bun --packages external && bun build src/serve/index.ts --outdir dist/serve --target bun --packages external && bun build src/index.ts src/service.ts src/handlers.ts src/agent-tools.ts src/types.ts --root src --outdir dist --target bun --packages external",
+    "build:types": "rm -rf types && tsc -p tsconfig.build.json --emitDeclarationOnly --outDir types",
+    "artifact-scan": "bun scripts/contracts-cli.mjs artifact-scan dist",
+    "contract:check": "bun scripts/contracts-cli.mjs repo-conformance .",
+    typecheck: "tsc --noEmit",
+    test: "bun test",
+    "test:pg": 'WORKFLOWS_TEST_DATABASE_URL="${WORKFLOWS_TEST_DATABASE_URL:?point it at a throwaway Postgres; the live-PG gate must not pass without one}" WORKFLOWS_REQUIRE_POSTGRES=1 bun test src/db/pg-live.test.ts',
+    prepack: "bun run build && bun run artifact-scan",
+    prepublishOnly: "bun run test && bun run build"
+  },
+  keywords: [
+    "workflows",
+    "graph",
+    "automation",
+    "cli",
+    "typescript",
+    "bun",
+    "hasna"
+  ],
+  publishConfig: {
+    registry: "https://registry.npmjs.org",
+    access: "public"
+  },
+  repository: {
+    type: "git",
+    url: "git+https://github.com/hasna/apps.git"
+  },
+  homepage: "https://github.com/hasna/apps/tree/main/apps/workflows",
+  bugs: {
+    url: "https://github.com/hasna/apps/issues"
+  },
+  engines: {
+    bun: ">=1.0.0",
+    node: ">=20.0.0"
+  },
+  author: "Hasna",
+  license: "Apache-2.0",
+  dependencies: {
+    commander: "^13.1.0"
+  },
+  devDependencies: {
+    "@hasna/contracts": "0.14.0",
+    "@types/bun": "latest",
+    "@types/pg": "^8.15.6",
+    pg: "^8.16.3",
+    typescript: "^5.7.3"
+  }
+};
+
+// src/service.ts
+var DEFAULT_PORT = 8790;
+var DEFAULT_HOST = "127.0.0.1";
+function packageVersion() {
+  return package_default.version;
+}
+function envString(names) {
+  for (const name of names) {
+    const value = process.env[name];
+    if (value !== undefined && value !== "")
+      return value;
+  }
+  return;
+}
+function envInt(names, fallback) {
+  const value = envString(names);
+  if (value === undefined)
+    return fallback;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+function resolveWorkflowsConfig(overrides = {}) {
+  const home = process.env.HOME ?? process.env.USERPROFILE ?? ".";
+  return {
+    port: overrides.port ?? envInt(["HASNA_WORKFLOWS_PORT", "WORKFLOWS_PORT"], DEFAULT_PORT),
+    host: overrides.host ?? envString(["HASNA_WORKFLOWS_HOST", "WORKFLOWS_HOST"]) ?? DEFAULT_HOST,
+    dataDir: overrides.dataDir ?? envString(["HASNA_WORKFLOWS_DATA_DIR", "WORKFLOWS_DATA_DIR"]) ?? join(home, ".hasna", "workflows"),
+    apiUrl: overrides.apiUrl ?? envString(["WORKFLOWS_API_URL"]),
+    apiKey: overrides.apiKey ?? envString(["WORKFLOWS_API_KEY"])
+  };
+}
+
+class WorkflowsService {
+  name = "workflows";
+  version;
+  config;
+  startedAt = Date.now();
+  constructor(config = {}) {
+    this.config = resolveWorkflowsConfig(config);
+    this.version = packageVersion();
+  }
+  health() {
+    return {
+      ok: true,
+      service: this.name,
+      version: this.version,
+      pid: process.pid,
+      uptimeMs: Date.now() - this.startedAt
+    };
+  }
+  ready() {
+    return {
+      ok: true,
+      service: this.name,
+      version: this.version,
+      checks: { version: "ok" }
+    };
+  }
+}
+function createWorkflowsService(config = {}) {
+  return new WorkflowsService(config);
+}
+
+// src/handlers.ts
+function jsonResponse(body, status = 200) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" }
+  });
+}
+function openApiDoc(service) {
+  return {
+    openapi: "3.0.3",
+    info: { title: "workflows", version: service.version },
+    paths: {
+      "/health": { get: { summary: "Service health", responses: { "200": { description: "ok" } } } },
+      "/ready": { get: { summary: "Service readiness", responses: { "200": { description: "ok" } } } },
+      "/version": { get: { summary: "Service version", responses: { "200": { description: "ok" } } } }
+    }
+  };
+}
+function createRequestHandler(service) {
+  return (req) => {
+    const url = new URL(req.url);
+    switch (url.pathname) {
+      case "/health":
+        return jsonResponse(service.health());
+      case "/ready":
+        return jsonResponse(service.ready());
+      case "/version":
+        return jsonResponse({ service: service.name, version: service.version });
+      case "/openapi.json":
+        return jsonResponse(openApiDoc(service));
+      default:
+        return jsonResponse({ error: "not_found", path: url.pathname }, 404);
+    }
+  };
+}
+
+// src/serve/server.ts
+function createWorkflowsServer(service) {
+  const handler = createRequestHandler(service);
+  const server = Bun.serve({
+    hostname: service.config.host,
+    port: service.config.port,
+    fetch: handler
+  });
+  return {
+    port: server.port ?? 0,
+    stop: () => {
+      server.stop();
+    }
+  };
+}
+
+// src/serve/index.ts
+var HELP_TEXT = `workflows-serve \u2014 HTTP server for @hasna/workflows
+
+Usage:
+  workflows-serve [--version] [--help]
+
+Endpoints:
+  /health         service health
+  /ready          service readiness
+  /version        service version
+  /openapi.json   API document
+
+Configuration (env):
+  HASNA_WORKFLOWS_PORT  port (default 8790)
+  HASNA_WORKFLOWS_HOST  bind host (default 127.0.0.1)`;
+var argv = process.argv.slice(2);
+if (argv.includes("--version") || argv.includes("-v")) {
+  console.log(packageVersion());
+  process.exit(0);
+}
+if (argv.includes("--help") || argv.includes("-h")) {
+  console.log(HELP_TEXT);
+  process.exit(0);
+}
+var service = createWorkflowsService();
+var server = createWorkflowsServer(service);
+console.log(`workflows-serve listening on http://${service.config.host}:${server.port}`);

package/dist/service.js

@@ -0,0 +1,156 @@
+// @bun
+// src/service.ts
+import { join } from "path";
+// package.json
+var package_default = {
+  name: "@hasna/workflows",
+  version: "0.1.0",
+  description: "Universal graph workflow app \u2014 scaffold with version/health/readiness on all four surfaces; graph language, store, session WAL, daemon, and lane adapters are roadmap",
+  type: "module",
+  main: "./dist/index.js",
+  types: "./types/index.d.ts",
+  bin: {
+    workflows: "dist/cli/index.js",
+    "workflows-mcp": "dist/mcp/index.js",
+    "workflows-serve": "dist/serve/index.js"
+  },
+  exports: {
+    ".": {
+      types: "./types/index.d.ts",
+      import: "./dist/index.js"
+    },
+    "./sdk": {
+      types: "./types/index.d.ts",
+      import: "./dist/index.js"
+    },
+    "./cli": {
+      types: "./types/cli/index.d.ts",
+      import: "./dist/cli/index.js"
+    }
+  },
+  files: [
+    "dist",
+    "types",
+    "README.md",
+    "LICENSE",
+    "hasna.contract.json"
+  ],
+  scripts: {
+    build: "bun run build:runtime && bun run build:types",
+    "build:runtime": "rm -rf dist && bun build src/cli/index.ts --outdir dist/cli --target bun --packages external && bun build src/mcp/index.ts --outdir dist/mcp --target bun --packages external && bun build src/serve/index.ts --outdir dist/serve --target bun --packages external && bun build src/index.ts src/service.ts src/handlers.ts src/agent-tools.ts src/types.ts --root src --outdir dist --target bun --packages external",
+    "build:types": "rm -rf types && tsc -p tsconfig.build.json --emitDeclarationOnly --outDir types",
+    "artifact-scan": "bun scripts/contracts-cli.mjs artifact-scan dist",
+    "contract:check": "bun scripts/contracts-cli.mjs repo-conformance .",
+    typecheck: "tsc --noEmit",
+    test: "bun test",
+    "test:pg": 'WORKFLOWS_TEST_DATABASE_URL="${WORKFLOWS_TEST_DATABASE_URL:?point it at a throwaway Postgres; the live-PG gate must not pass without one}" WORKFLOWS_REQUIRE_POSTGRES=1 bun test src/db/pg-live.test.ts',
+    prepack: "bun run build && bun run artifact-scan",
+    prepublishOnly: "bun run test && bun run build"
+  },
+  keywords: [
+    "workflows",
+    "graph",
+    "automation",
+    "cli",
+    "typescript",
+    "bun",
+    "hasna"
+  ],
+  publishConfig: {
+    registry: "https://registry.npmjs.org",
+    access: "public"
+  },
+  repository: {
+    type: "git",
+    url: "git+https://github.com/hasna/apps.git"
+  },
+  homepage: "https://github.com/hasna/apps/tree/main/apps/workflows",
+  bugs: {
+    url: "https://github.com/hasna/apps/issues"
+  },
+  engines: {
+    bun: ">=1.0.0",
+    node: ">=20.0.0"
+  },
+  author: "Hasna",
+  license: "Apache-2.0",
+  dependencies: {
+    commander: "^13.1.0"
+  },
+  devDependencies: {
+    "@hasna/contracts": "0.14.0",
+    "@types/bun": "latest",
+    "@types/pg": "^8.15.6",
+    pg: "^8.16.3",
+    typescript: "^5.7.3"
+  }
+};
+
+// src/service.ts
+var DEFAULT_PORT = 8790;
+var DEFAULT_HOST = "127.0.0.1";
+function packageVersion() {
+  return package_default.version;
+}
+function envString(names) {
+  for (const name of names) {
+    const value = process.env[name];
+    if (value !== undefined && value !== "")
+      return value;
+  }
+  return;
+}
+function envInt(names, fallback) {
+  const value = envString(names);
+  if (value === undefined)
+    return fallback;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+function resolveWorkflowsConfig(overrides = {}) {
+  const home = process.env.HOME ?? process.env.USERPROFILE ?? ".";
+  return {
+    port: overrides.port ?? envInt(["HASNA_WORKFLOWS_PORT", "WORKFLOWS_PORT"], DEFAULT_PORT),
+    host: overrides.host ?? envString(["HASNA_WORKFLOWS_HOST", "WORKFLOWS_HOST"]) ?? DEFAULT_HOST,
+    dataDir: overrides.dataDir ?? envString(["HASNA_WORKFLOWS_DATA_DIR", "WORKFLOWS_DATA_DIR"]) ?? join(home, ".hasna", "workflows"),
+    apiUrl: overrides.apiUrl ?? envString(["WORKFLOWS_API_URL"]),
+    apiKey: overrides.apiKey ?? envString(["WORKFLOWS_API_KEY"])
+  };
+}
+
+class WorkflowsService {
+  name = "workflows";
+  version;
+  config;
+  startedAt = Date.now();
+  constructor(config = {}) {
+    this.config = resolveWorkflowsConfig(config);
+    this.version = packageVersion();
+  }
+  health() {
+    return {
+      ok: true,
+      service: this.name,
+      version: this.version,
+      pid: process.pid,
+      uptimeMs: Date.now() - this.startedAt
+    };
+  }
+  ready() {
+    return {
+      ok: true,
+      service: this.name,
+      version: this.version,
+      checks: { version: "ok" }
+    };
+  }
+}
+function createWorkflowsService(config = {}) {
+  return new WorkflowsService(config);
+}
+export {
+  resolveWorkflowsConfig,
+  packageVersion,
+  createWorkflowsService,
+  WorkflowsService
+};

package/dist/types.js

@@ -0,0 +1 @@
+// @bun

package/hasna.contract.json

@@ -0,0 +1,94 @@
+{
+  "schema": "hasna.service_contract.v1",
+  "name": "workflows",
+  "class": "service",
+  "contractVersion": "v1",
+  "kitVersion": "0.14.0",
+  "description": "Scaffold of the universal graph workflow app: version/health/readiness on all four surfaces (CLI, MCP, serve, SDK). The graph language, three-table store, session WAL, claims/leases daemon, and lane adapters (claude, codex, cursor, grok) are roadmap slices not shipped in 0.1.0.",
+  "bins": [
+    "workflows",
+    "workflows-mcp",
+    "workflows-serve"
+  ],
+  "hosting": [
+    "user-hosted"
+  ],
+  "serviceSurfaces": [
+    {
+      "name": "http-api",
+      "kind": "api",
+      "status": "supported",
+      "bin": "workflows-serve",
+      "authMode": "local-only",
+      "health": {
+        "method": "GET",
+        "path": "/health",
+        "public": true
+      },
+      "readiness": {
+        "method": "GET",
+        "path": "/ready",
+        "public": true
+      },
+      "version": {
+        "method": "GET",
+        "path": "/version",
+        "public": true
+      },
+      "openApiPath": "/openapi.json"
+    },
+    {
+      "name": "typescript-sdk",
+      "kind": "sdk",
+      "status": "supported",
+      "authMode": "local-only",
+      "exportSubpath": "./sdk",
+      "clientClassName": "WorkflowsService",
+      "generatedFrom": "/openapi.json"
+    },
+    {
+      "name": "mcp",
+      "kind": "mcp",
+      "status": "supported",
+      "mcpBin": "workflows-mcp",
+      "authMode": "local-only"
+    },
+    {
+      "name": "cli",
+      "kind": "cli",
+      "status": "supported",
+      "bin": "workflows",
+      "authMode": "local-only"
+    }
+  ],
+  "metadata": {
+    "serve": {
+      "healthEndpoints": [
+        "/health",
+        "/ready",
+        "/version"
+      ],
+      "openapi": "/openapi.json",
+      "auth": "local-only"
+    },
+    "release": {
+      "artifactScan": {
+        "script": "artifact-scan"
+      }
+    }
+  },
+  "storage": {
+    "backend": "sqlite",
+    "engines": [
+      "sqlite",
+      "postgresql"
+    ],
+    "envPrefix": "HASNA_WORKFLOWS_",
+    "aliasEnvPrefix": "WORKFLOWS_",
+    "sqlitePath": "~/.hasna/workflows/workflows.db",
+    "pgTestGate": {
+      "envVar": "WORKFLOWS_TEST_DATABASE_URL",
+      "command": "bun run test:pg"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@hasna/workflows",
+  "version": "0.1.0",
+  "description": "Universal graph workflow app \u2014 scaffold with version/health/readiness on all four surfaces; graph language, store, session WAL, daemon, and lane adapters are roadmap",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./types/index.d.ts",
+  "bin": {
+    "workflows": "dist/cli/index.js",
+    "workflows-mcp": "dist/mcp/index.js",
+    "workflows-serve": "dist/serve/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./sdk": {
+      "types": "./types/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./cli": {
+      "types": "./types/cli/index.d.ts",
+      "import": "./dist/cli/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "types",
+    "README.md",
+    "LICENSE",
+    "hasna.contract.json"
+  ],
+  "scripts": {
+    "build": "bun run build:runtime && bun run build:types",
+    "build:runtime": "rm -rf dist && bun build src/cli/index.ts --outdir dist/cli --target bun --packages external && bun build src/mcp/index.ts --outdir dist/mcp --target bun --packages external && bun build src/serve/index.ts --outdir dist/serve --target bun --packages external && bun build src/index.ts src/service.ts src/handlers.ts src/agent-tools.ts src/types.ts --root src --outdir dist --target bun --packages external",
+    "build:types": "rm -rf types && tsc -p tsconfig.build.json --emitDeclarationOnly --outDir types",
+    "artifact-scan": "bun scripts/contracts-cli.mjs artifact-scan dist",
+    "contract:check": "bun scripts/contracts-cli.mjs repo-conformance .",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "test:pg": "WORKFLOWS_TEST_DATABASE_URL=\"${WORKFLOWS_TEST_DATABASE_URL:?point it at a throwaway Postgres; the live-PG gate must not pass without one}\" WORKFLOWS_REQUIRE_POSTGRES=1 bun test src/db/pg-live.test.ts",
+    "prepack": "bun run build && bun run artifact-scan",
+    "prepublishOnly": "bun run test && bun run build"
+  },
+  "keywords": [
+    "workflows",
+    "graph",
+    "automation",
+    "cli",
+    "typescript",
+    "bun",
+    "hasna"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hasna/apps.git"
+  },
+  "homepage": "https://github.com/hasna/apps/tree/main/apps/workflows",
+  "bugs": {
+    "url": "https://github.com/hasna/apps/issues"
+  },
+  "engines": {
+    "bun": ">=1.0.0",
+    "node": ">=20.0.0"
+  },
+  "author": "Hasna",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "commander": "^13.1.0"
+  },
+  "devDependencies": {
+    "@hasna/contracts": "0.14.0",
+    "@types/bun": "latest",
+    "@types/pg": "^8.15.6",
+    "pg": "^8.16.3",
+    "typescript": "^5.7.3"
+  }
+}

package/types/agent-tools.d.ts

@@ -0,0 +1,23 @@
+/**
+ * MCP tool registry for @hasna/workflows — the agent interface layer over
+ * WorkflowsService. Slice 1 ships identity/health tools; the graph language,
+ * store, and daemon slices add their tools here.
+ */
+import type { WorkflowsService } from "./service.js";
+export interface McpTool {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: Record<string, unknown>;
+    };
+}
+export interface ToolCallResult {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+}
+export declare function workflowsTools(_service: WorkflowsService): McpTool[];
+export declare function callWorkflowTool(service: WorkflowsService, name: string, _args: Record<string, unknown>): ToolCallResult;

package/types/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/types/handlers.d.ts

@@ -0,0 +1,7 @@
+/**
+ * HTTP request handler for workflows-serve. Interface layer over
+ * WorkflowsService; all business logic lives in the service.
+ */
+import type { WorkflowsService } from "./service.js";
+export declare function jsonResponse(body: unknown, status?: number): Response;
+export declare function createRequestHandler(service: WorkflowsService): (req: Request) => Response;

package/types/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @hasna/workflows SDK entry — the importable module surface.
+ * Re-exports the domain service, the HTTP handlers, and the MCP tool
+ * registry so every surface is reachable programmatically.
+ */
+export { WorkflowsService, createWorkflowsService, packageVersion, resolveWorkflowsConfig } from "./service.js";
+export { createRequestHandler, jsonResponse } from "./handlers.js";
+export { workflowsTools, callWorkflowTool } from "./agent-tools.js";
+export type { WorkflowsConfig, HealthReport, ReadinessReport } from "./types.js";
+export type { McpTool, ToolCallResult } from "./agent-tools.js";

package/types/mcp/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/types/serve/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/types/serve/server.d.ts

@@ -0,0 +1,10 @@
+/**
+ * HTTP server factory for workflows-serve. Interface layer over
+ * WorkflowsService; the bin (src/serve/index.ts) wires args + lifecycle.
+ */
+import type { WorkflowsService } from "../service.js";
+export interface WorkflowsServer {
+    port: number;
+    stop: () => void;
+}
+export declare function createWorkflowsServer(service: WorkflowsService): WorkflowsServer;

package/types/service.d.ts

@@ -0,0 +1,14 @@
+import type { HealthReport, ReadinessReport, WorkflowsConfig } from "./types.js";
+export declare function packageVersion(): string;
+/** Resolve the service configuration from env + explicit overrides. */
+export declare function resolveWorkflowsConfig(overrides?: Partial<WorkflowsConfig>): WorkflowsConfig;
+export declare class WorkflowsService {
+    readonly name = "workflows";
+    readonly version: string;
+    readonly config: WorkflowsConfig;
+    private readonly startedAt;
+    constructor(config?: Partial<WorkflowsConfig>);
+    health(): HealthReport;
+    ready(): ReadinessReport;
+}
+export declare function createWorkflowsService(config?: Partial<WorkflowsConfig>): WorkflowsService;

package/types/types.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared surface types for @hasna/workflows.
+ *
+ * Slice 1 (scaffold): identity, health, readiness, and config. Later slices
+ * extend these with the graph language, store, session, and daemon types.
+ */
+/** Resolved service configuration. Values are resolved from the
+ * HASNA_WORKFLOWS_ and WORKFLOWS_ environment prefixes with documented
+ * defaults. */
+export interface WorkflowsConfig {
+    /** HTTP port for workflows-serve. Default 8790. */
+    port: number;
+    /** Bind host for workflows-serve. Default 127.0.0.1. */
+    host: string;
+    /** Data directory (store slice lands the db here). Default ~/.hasna/workflows. */
+    dataDir: string;
+    /** Optional client API URL (WORKFLOWS_API_URL) — consumed by later slices. */
+    apiUrl?: string;
+    /** Optional client API key (WORKFLOWS_API_KEY) — resolved, never printed. */
+    apiKey?: string;
+}
+export interface HealthReport {
+    ok: boolean;
+    service: string;
+    version: string;
+    pid: number;
+    uptimeMs: number;
+}
+export interface ReadinessReport {
+    ok: boolean;
+    service: string;
+    version: string;
+    checks: Record<string, string>;
+}