@devory/core 0.0.1 → 0.1.0

package/README.md

@@ -0,0 +1,41 @@
+# @devory/core
+
+Shared types, parsing utilities, and path configuration for [Devory](https://devory.ai).
+
+## Installation
+
+```bash
+npm install @devory/core
+```
+
+## API
+
+### Task parsing
+
+```ts
+import { parseFrontmatter } from '@devory/core'
+
+const result = parseFrontmatter(fileContent)
+// result.meta — typed TaskMeta fields
+// result.body — markdown body after frontmatter
+```
+
+### Factory environment
+
+```ts
+import { resolveFactoryEnvironment, factoryPaths } from '@devory/core'
+
+const env = resolveFactoryEnvironment()
+const paths = factoryPaths(env.root)
+// paths.tasksDir, paths.runsDir, paths.artifactsDir, etc.
+```
+
+## Types
+
+- `TaskMeta` — frontmatter fields for a Devory task file
+- `FactoryEnvironment` — resolved root, mode, and source
+- `FactoryPaths` — all well-known directories in a factory workspace
+
+## Requirements
+
+- Node.js 18+

package/dist/index.js

@@ -0,0 +1,148 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  factoryPaths: () => factoryPaths,
+  findFactoryContextDir: () => findFactoryContextDir,
+  parseFrontmatter: () => parseFrontmatter,
+  resolveFactoryEnvironment: () => resolveFactoryEnvironment,
+  resolveFactoryMode: () => resolveFactoryMode,
+  resolveFactoryRoot: () => resolveFactoryRoot
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/parse.ts
+function parseFrontmatter(content) {
+  const lines = content.split("\n");
+  if (lines[0]?.trim() !== "---") {
+    return { meta: {}, body: content };
+  }
+  const closeIdx = lines.indexOf("---", 1);
+  if (closeIdx === -1) {
+    return { meta: {}, body: content };
+  }
+  const yamlLines = lines.slice(1, closeIdx);
+  const body = lines.slice(closeIdx + 1).join("\n");
+  const meta = {};
+  let currentKey = "";
+  for (const line of yamlLines) {
+    const listMatch = line.match(/^\s+-\s+(.*)/);
+    const kvMatch = line.match(/^([\w_][\w_-]*):\s*(.*)/);
+    if (listMatch && currentKey) {
+      const arr = meta[currentKey];
+      if (Array.isArray(arr)) {
+        arr.push(listMatch[1].trim());
+      }
+    } else if (kvMatch) {
+      currentKey = kvMatch[1];
+      const val = kvMatch[2].trim();
+      if (val === "" || val === "[]") {
+        meta[currentKey] = [];
+      } else {
+        meta[currentKey] = val;
+      }
+    }
+  }
+  return { meta, body };
+}
+
+// src/factory-environment.ts
+var fs = __toESM(require("fs"));
+var path = __toESM(require("path"));
+var FACTORY_MARKER = "FACTORY_CONTEXT.md";
+function trimEnv(value) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed === "" ? null : trimmed;
+}
+function findFactoryContextDir(startDir) {
+  let current = path.resolve(startDir);
+  while (true) {
+    if (fs.existsSync(path.join(current, FACTORY_MARKER))) {
+      return current;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return null;
+    }
+    current = parent;
+  }
+}
+function resolveFactoryRoot(startDir = process.cwd()) {
+  const explicit = trimEnv(process.env.DEVORY_FACTORY_ROOT);
+  if (explicit) {
+    return { root: explicit, source: "env:DEVORY_FACTORY_ROOT" };
+  }
+  const legacy = trimEnv(process.env.FACTORY_ROOT);
+  if (legacy) {
+    return { root: legacy, source: "env:FACTORY_ROOT" };
+  }
+  const walked = findFactoryContextDir(startDir);
+  if (walked) {
+    return { root: walked, source: "git-walk" };
+  }
+  return { root: path.resolve(startDir), source: "cwd" };
+}
+function factoryPaths(root) {
+  return {
+    tasksDir: path.join(root, "tasks"),
+    runsDir: path.join(root, "runs"),
+    artifactsDir: path.join(root, "artifacts"),
+    contextFile: path.join(root, FACTORY_MARKER)
+  };
+}
+function resolveFactoryMode(env = process.env) {
+  const explicitMode = trimEnv(env.DEVORY_FACTORY_MODE) ?? trimEnv(env.FACTORY_MODE);
+  if (explicitMode === "hosted") return "hosted";
+  if (explicitMode === "local") return "local";
+  if (trimEnv(env.DEVORY_REMOTE_FACTORY_URL) || trimEnv(env.FACTORY_REMOTE_URL)) {
+    return "hosted";
+  }
+  return "local";
+}
+function resolveFactoryEnvironment(startDir = process.cwd(), env = process.env) {
+  const { root, source } = resolveFactoryRoot(startDir);
+  return {
+    root,
+    source,
+    mode: resolveFactoryMode(env),
+    paths: factoryPaths(root)
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  factoryPaths,
+  findFactoryContextDir,
+  parseFrontmatter,
+  resolveFactoryEnvironment,
+  resolveFactoryMode,
+  resolveFactoryRoot
+});

package/package.json

@@ -1,7 +1,24 @@
 {
   "name": "@devory/core",
-  "version": "0.0.1",
-  "description": "Devory core platform",
-  "main": "index.js",
-  "license": "MIT"
+  "version": "0.1.0",
+  "description": "Shared types, parsing utilities, and path configuration for AI Dev Factory",
+  "main": "./dist/index.js",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --outfile=dist/index.js --platform=node --format=cjs",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "esbuild": "^0.20.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3"
+  }
 }

package/src/factory-environment.test.ts

@@ -0,0 +1,99 @@
+import { afterEach, beforeEach, describe, test } from "node:test";
+import assert from "node:assert/strict";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+
+import {
+  factoryPaths,
+  findFactoryContextDir,
+  resolveFactoryEnvironment,
+  resolveFactoryMode,
+  resolveFactoryRoot,
+} from "./factory-environment.ts";
+
+let tmpDir: string;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "factory-env-test-"));
+  delete process.env.DEVORY_FACTORY_ROOT;
+  delete process.env.FACTORY_ROOT;
+  delete process.env.DEVORY_FACTORY_MODE;
+  delete process.env.FACTORY_MODE;
+  delete process.env.DEVORY_REMOTE_FACTORY_URL;
+  delete process.env.FACTORY_REMOTE_URL;
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+  delete process.env.DEVORY_FACTORY_ROOT;
+  delete process.env.FACTORY_ROOT;
+  delete process.env.DEVORY_FACTORY_MODE;
+  delete process.env.FACTORY_MODE;
+  delete process.env.DEVORY_REMOTE_FACTORY_URL;
+  delete process.env.FACTORY_REMOTE_URL;
+});
+
+describe("findFactoryContextDir", () => {
+  test("returns the containing directory when marker exists", () => {
+    fs.writeFileSync(path.join(tmpDir, "FACTORY_CONTEXT.md"), "# context");
+    assert.equal(findFactoryContextDir(tmpDir), tmpDir);
+  });
+
+  test("walks up parent directories to find the factory marker", () => {
+    fs.writeFileSync(path.join(tmpDir, "FACTORY_CONTEXT.md"), "# context");
+    const nested = path.join(tmpDir, "nested", "deep");
+    fs.mkdirSync(nested, { recursive: true });
+    assert.equal(findFactoryContextDir(nested), tmpDir);
+  });
+});
+
+describe("resolveFactoryRoot", () => {
+  test("uses DEVORY_FACTORY_ROOT first", () => {
+    process.env.DEVORY_FACTORY_ROOT = "/explicit/path";
+    process.env.FACTORY_ROOT = "/legacy/path";
+    assert.deepEqual(resolveFactoryRoot(tmpDir), {
+      root: "/explicit/path",
+      source: "env:DEVORY_FACTORY_ROOT",
+    });
+  });
+
+  test("walks to the factory marker when env vars are absent", () => {
+    fs.writeFileSync(path.join(tmpDir, "FACTORY_CONTEXT.md"), "# context");
+    const nested = path.join(tmpDir, "deep");
+    fs.mkdirSync(nested);
+    assert.deepEqual(resolveFactoryRoot(nested), {
+      root: tmpDir,
+      source: "git-walk",
+    });
+  });
+});
+
+describe("resolveFactoryMode", () => {
+  test("defaults to local", () => {
+    assert.equal(resolveFactoryMode(), "local");
+  });
+
+  test("honors explicit hosted mode", () => {
+    process.env.DEVORY_FACTORY_MODE = "hosted";
+    assert.equal(resolveFactoryMode(), "hosted");
+  });
+
+  test("treats remote url configuration as hosted mode", () => {
+    process.env.DEVORY_REMOTE_FACTORY_URL = "https://factory.example.com";
+    assert.equal(resolveFactoryMode(), "hosted");
+  });
+});
+
+describe("resolveFactoryEnvironment", () => {
+  test("returns root, mode, and derived paths together", () => {
+    fs.writeFileSync(path.join(tmpDir, "FACTORY_CONTEXT.md"), "# context");
+    process.env.DEVORY_FACTORY_MODE = "hosted";
+
+    const result = resolveFactoryEnvironment(tmpDir);
+    assert.equal(result.root, tmpDir);
+    assert.equal(result.source, "git-walk");
+    assert.equal(result.mode, "hosted");
+    assert.deepEqual(result.paths, factoryPaths(tmpDir));
+  });
+});

package/src/factory-environment.ts

@@ -0,0 +1,103 @@
+import * as fs from "fs";
+import * as path from "path";
+
+export type FactoryRootSource =
+  | "env:DEVORY_FACTORY_ROOT"
+  | "env:FACTORY_ROOT"
+  | "git-walk"
+  | "cwd";
+
+export type FactoryMode = "local" | "hosted";
+
+export interface FactoryPaths {
+  tasksDir: string;
+  runsDir: string;
+  artifactsDir: string;
+  contextFile: string;
+}
+
+export interface FactoryEnvironment {
+  root: string;
+  source: FactoryRootSource;
+  mode: FactoryMode;
+  paths: FactoryPaths;
+}
+
+const FACTORY_MARKER = "FACTORY_CONTEXT.md";
+
+function trimEnv(value: string | undefined): string | null {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed === "" ? null : trimmed;
+}
+
+export function findFactoryContextDir(startDir: string): string | null {
+  let current = path.resolve(startDir);
+
+  while (true) {
+    if (fs.existsSync(path.join(current, FACTORY_MARKER))) {
+      return current;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return null;
+    }
+    current = parent;
+  }
+}
+
+export function resolveFactoryRoot(startDir = process.cwd()): {
+  root: string;
+  source: FactoryRootSource;
+} {
+  const explicit = trimEnv(process.env.DEVORY_FACTORY_ROOT);
+  if (explicit) {
+    return { root: explicit, source: "env:DEVORY_FACTORY_ROOT" };
+  }
+
+  const legacy = trimEnv(process.env.FACTORY_ROOT);
+  if (legacy) {
+    return { root: legacy, source: "env:FACTORY_ROOT" };
+  }
+
+  const walked = findFactoryContextDir(startDir);
+  if (walked) {
+    return { root: walked, source: "git-walk" };
+  }
+
+  return { root: path.resolve(startDir), source: "cwd" };
+}
+
+export function factoryPaths(root: string): FactoryPaths {
+  return {
+    tasksDir: path.join(root, "tasks"),
+    runsDir: path.join(root, "runs"),
+    artifactsDir: path.join(root, "artifacts"),
+    contextFile: path.join(root, FACTORY_MARKER),
+  };
+}
+
+export function resolveFactoryMode(env: NodeJS.ProcessEnv = process.env): FactoryMode {
+  const explicitMode = trimEnv(env.DEVORY_FACTORY_MODE) ?? trimEnv(env.FACTORY_MODE);
+  if (explicitMode === "hosted") return "hosted";
+  if (explicitMode === "local") return "local";
+
+  if (trimEnv(env.DEVORY_REMOTE_FACTORY_URL) || trimEnv(env.FACTORY_REMOTE_URL)) {
+    return "hosted";
+  }
+
+  return "local";
+}
+
+export function resolveFactoryEnvironment(
+  startDir = process.cwd(),
+  env: NodeJS.ProcessEnv = process.env
+): FactoryEnvironment {
+  const { root, source } = resolveFactoryRoot(startDir);
+  return {
+    root,
+    source,
+    mode: resolveFactoryMode(env),
+    paths: factoryPaths(root),
+  };
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+/**
+ * @devory/core — public API
+ *
+ * Shared types, parsing utilities, and path configuration
+ * for the AI Dev Factory monorepo.
+ */
+
+export { parseFrontmatter } from "./parse.ts";
+export type { TaskMeta, ParseResult } from "./parse.ts";
+export {
+  factoryPaths,
+  findFactoryContextDir,
+  resolveFactoryEnvironment,
+  resolveFactoryMode,
+  resolveFactoryRoot,
+} from "./factory-environment.ts";
+export type {
+  FactoryEnvironment,
+  FactoryMode,
+  FactoryPaths,
+  FactoryRootSource,
+} from "./factory-environment.ts";

package/src/parse.test.ts

@@ -0,0 +1,161 @@
+/**
+ * @devory/core — parseFrontmatter tests.
+ *
+ * Run from factory root: tsx --test packages/core/src/parse.test.ts
+ */
+
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import { parseFrontmatter } from "./parse.js";
+
+// ── Basic parsing ─────────────────────────────────────────────────────────────
+
+describe("parseFrontmatter", () => {
+  test("parses a minimal frontmatter block", () => {
+    const content = `---
+id: factory-001
+title: My Task
+status: backlog
+---
+Body text here.`;
+    const { meta, body } = parseFrontmatter(content);
+    assert.equal(meta.id, "factory-001");
+    assert.equal(meta.title, "My Task");
+    assert.equal(meta.status, "backlog");
+    assert.ok(body.includes("Body text here."));
+  });
+
+  test("returns empty meta and full content when no frontmatter delimiter", () => {
+    const content = "No frontmatter here.";
+    const { meta, body } = parseFrontmatter(content);
+    assert.deepEqual(meta, {});
+    assert.equal(body, content);
+  });
+
+  test("returns empty meta when opening delimiter missing", () => {
+    const content = "id: factory-001\n---\nbody";
+    const { meta } = parseFrontmatter(content);
+    assert.deepEqual(meta, {});
+  });
+
+  test("returns empty meta when closing delimiter missing", () => {
+    const content = "---\nid: factory-001\nbody without close";
+    const { meta } = parseFrontmatter(content);
+    assert.deepEqual(meta, {});
+  });
+
+  test("parses string arrays from list items", () => {
+    const content = `---
+depends_on:
+  - factory-001
+  - factory-002
+---
+`;
+    const { meta } = parseFrontmatter(content);
+    assert.deepEqual(meta.depends_on, ["factory-001", "factory-002"]);
+  });
+
+  test("parses empty array from empty value", () => {
+    const content = `---
+depends_on:
+---
+`;
+    const { meta } = parseFrontmatter(content);
+    assert.deepEqual(meta.depends_on, []);
+  });
+
+  test("parses empty array from [] syntax", () => {
+    const content = `---
+depends_on: []
+---
+`;
+    const { meta } = parseFrontmatter(content);
+    assert.deepEqual(meta.depends_on, []);
+  });
+
+  test("body does not include frontmatter", () => {
+    const content = `---
+id: factory-001
+---
+## Section
+Content here.`;
+    const { body } = parseFrontmatter(content);
+    assert.ok(!body.includes("id: factory-001"));
+    assert.ok(body.includes("## Section"));
+  });
+
+  test("parses all standard task fields", () => {
+    const content = `---
+id: factory-010
+title: Test Task
+project: ai-dev-factory
+repo: .
+branch: task/factory-010
+type: feature
+priority: high
+status: ready
+agent: fullstack-builder
+---
+`;
+    const { meta } = parseFrontmatter(content);
+    assert.equal(meta.id, "factory-010");
+    assert.equal(meta.title, "Test Task");
+    assert.equal(meta.project, "ai-dev-factory");
+    assert.equal(meta.type, "feature");
+    assert.equal(meta.priority, "high");
+    assert.equal(meta.agent, "fullstack-builder");
+  });
+
+  test("parses verification list", () => {
+    const content = `---
+verification:
+  - npm run test
+  - npm run build
+---
+`;
+    const { meta } = parseFrontmatter(content);
+    assert.deepEqual(meta.verification, ["npm run test", "npm run build"]);
+  });
+
+  test("handles hyphen-containing keys like depends_on", () => {
+    const content = `---
+bundle-id: epic-auth
+---
+`;
+    const { meta } = parseFrontmatter(content);
+    assert.equal(meta["bundle-id"], "epic-auth");
+  });
+
+  test("trims whitespace from scalar values", () => {
+    const content = `---
+title:   My Task
+status:  backlog
+---
+`;
+    const { meta } = parseFrontmatter(content);
+    assert.equal(meta.title, "My Task");
+    assert.equal(meta.status, "backlog");
+  });
+
+  test("ignores list items before any key is set", () => {
+    const content = `---
+  - orphaned-item
+id: factory-001
+---
+`;
+    const { meta } = parseFrontmatter(content);
+    assert.equal(meta.id, "factory-001");
+  });
+
+  test("empty content returns empty meta and empty body", () => {
+    const { meta, body } = parseFrontmatter("");
+    assert.deepEqual(meta, {});
+    assert.equal(body, "");
+  });
+
+  test("content with only delimiter lines returns empty meta", () => {
+    const content = "---\n---\n";
+    const { meta } = parseFrontmatter(content);
+    assert.deepEqual(meta, {});
+  });
+});

package/src/parse.ts

@@ -0,0 +1,103 @@
+/**
+ * @devory/core — shared frontmatter parsing utilities.
+ *
+ * Pure functions with no external dependencies.
+ * Used by workers/lib, scripts, and apps/devory.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface TaskMeta {
+  id: string;
+  title: string;
+  project: string;
+  repo: string;
+  branch: string;
+  type: string;
+  priority: string;
+  status: string;
+  agent: string;
+  /** Simulated execution outcome written by an agent after doing work. */
+  execution_result?: string;
+  depends_on: string[];
+  files_likely_affected: string[];
+  verification: string[];
+
+  // Planner / parent-task fields (all optional)
+  planner?: boolean;
+  parent_task?: string;
+  lane?: string;
+  repo_area?: string;
+  decomposition_hint?: string;
+  required_capabilities?: string[];
+  preferred_capabilities?: string[];
+  disallowed_models?: string[];
+  preferred_models?: string[];
+  execution_profile?: string;
+  pipeline?: string;
+  context_intensity?: string;
+  quality_priority?: string;
+  speed_priority?: string;
+  max_cost_tier?: string;
+
+  // Bundle / epic fields (all optional)
+  bundle_id?: string;
+  bundle_title?: string;
+  bundle_phase?: string;
+
+  [key: string]: unknown;
+}
+
+export interface ParseResult {
+  meta: Partial<TaskMeta>;
+  body: string;
+}
+
+// ---------------------------------------------------------------------------
+// Frontmatter parser
+// Handles simple YAML: scalar strings and flat string arrays ("- item").
+// Does not depend on any external package.
+// ---------------------------------------------------------------------------
+
+export function parseFrontmatter(content: string): ParseResult {
+  const lines = content.split("\n");
+
+  if (lines[0]?.trim() !== "---") {
+    return { meta: {}, body: content };
+  }
+
+  const closeIdx = lines.indexOf("---", 1);
+  if (closeIdx === -1) {
+    return { meta: {}, body: content };
+  }
+
+  const yamlLines = lines.slice(1, closeIdx);
+  const body = lines.slice(closeIdx + 1).join("\n");
+  const meta: Partial<TaskMeta> = {};
+  let currentKey = "";
+
+  for (const line of yamlLines) {
+    const listMatch = line.match(/^\s+-\s+(.*)/);
+    const kvMatch = line.match(/^([\w_][\w_-]*):\s*(.*)/);
+
+    if (listMatch && currentKey) {
+      const arr = meta[currentKey];
+      if (Array.isArray(arr)) {
+        arr.push(listMatch[1].trim());
+      }
+    } else if (kvMatch) {
+      currentKey = kvMatch[1];
+      const val = kvMatch[2].trim();
+
+      if (val === "" || val === "[]") {
+        (meta as Record<string, unknown>)[currentKey] = [];
+      } else {
+        (meta as Record<string, unknown>)[currentKey] = val;
+      }
+    }
+  }
+
+  return { meta, body };
+}

package/index.js

@@ -1 +0,0 @@
-module.exports = {};