@devory/core 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devory/core",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Shared types, parsing utilities, and path configuration for AI Dev Factory",
   "main": "./dist/index.js",
   "types": "./src/index.ts",

package/src/defaults/generic.yml

@@ -0,0 +1,18 @@
+# Devory default baseline: generic
+# Stack-agnostic engineering standards distilled from core Devory doctrine.
+# Referenced via: extends: "@devory/defaults/generic"
+
+version: "1"
+
+doctrine:
+  testing:
+    require_unit: true
+    require_integration: false
+    coverage_threshold: 80
+
+  architecture:
+    max_file_lines: 300
+    no_circular_deps: true
+
+  code_style:
+    prefer_explicit_over_clever: true

package/src/defaults/typescript-nextjs.yml

@@ -0,0 +1,29 @@
+# Devory default baseline: TypeScript + Next.js
+# Extends the generic baseline with Next.js app-router conventions.
+# Referenced via: extends: "@devory/defaults/typescript-nextjs"
+
+version: "1"
+
+extends: "@devory/defaults/generic"
+
+stack:
+  language: TypeScript
+  framework: Next.js
+
+doctrine:
+  testing:
+    require_unit: true
+    require_integration: true
+    coverage_threshold: 80
+    avoid_mocking:
+      - database
+      - filesystem
+
+  architecture:
+    pattern: app-router
+    max_file_lines: 300
+    no_circular_deps: true
+
+  code_style:
+    no_any: true
+    prefer_explicit_over_clever: true

package/src/defaults/typescript-node.yml

@@ -0,0 +1,28 @@
+# Devory default baseline: TypeScript + Node.js
+# Extends the generic baseline with Node.js API / service conventions.
+# Referenced via: extends: "@devory/defaults/typescript-node"
+
+version: "1"
+
+extends: "@devory/defaults/generic"
+
+stack:
+  language: TypeScript
+  framework: Node.js
+
+doctrine:
+  testing:
+    require_unit: true
+    require_integration: true
+    coverage_threshold: 85
+    avoid_mocking:
+      - database
+
+  architecture:
+    pattern: layered
+    max_file_lines: 300
+    no_circular_deps: true
+
+  code_style:
+    no_any: true
+    prefer_explicit_over_clever: true

package/src/index.ts

@@ -1,8 +1,8 @@
 /**
  * @devory/core — public API
  *
- * Shared types, parsing utilities, and path configuration
- * for the AI Dev Factory monorepo.
+ * Shared types, parsing utilities, path configuration,
+ * engineering standards, and license tier detection.
  */
 
 export { parseFrontmatter } from "./parse.ts";
@@ -20,3 +20,28 @@ export type {
   FactoryPaths,
   FactoryRootSource,
 } from "./factory-environment.ts";
+export {
+  loadStandards,
+  loadBaseline,
+  mergeStandards,
+  resolveBaselinePath,
+  serializeStandardsAsDoctrine,
+  STANDARDS_FILENAME,
+} from "./standards.ts";
+export type {
+  Standards,
+  StandardsStack,
+  StandardsTesting,
+  StandardsArchitecture,
+  StandardsCodeStyle,
+  StandardsDoctrine,
+  StandardsSource,
+  StandardsSourceType,
+  LoadedStandards,
+} from "./standards.ts";
+export {
+  detectTier,
+  isFeatureEnabled,
+  tierGateMessage,
+} from "./license.ts";
+export type { Tier, ProFeature, LicenseInfo } from "./license.ts";

package/src/license.ts

@@ -0,0 +1,152 @@
+/**
+ * packages/core/src/license.ts
+ *
+ * Tier detection and Pro feature gating for Devory.
+ *
+ * Tiers:
+ *   Core  — no license key required; default baselines only; custom_rules ignored
+ *   Pro   — license key enables custom_rules and baseline overrides
+ *
+ * Key resolution order:
+ *   1. DEVORY_LICENSE_KEY environment variable
+ *   2. .devory/license file in the factory root
+ *   3. No key found → Core
+ *
+ * Network verification is stubbed — a real call will be wired once the
+ * license service exists. Local validation (format check) runs synchronously
+ * so Core tier never blocks on any network call.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type Tier = "core" | "pro";
+
+/** Features gated behind Pro tier. */
+export type ProFeature = "custom_rules" | "baseline_overrides" | "shared_doctrine" | "pr_gates";
+
+export interface LicenseInfo {
+  tier: Tier;
+  /** Raw key value, if one was found */
+  key?: string;
+  /** Where the key was found */
+  source?: "env" | "file";
+  /** True when a key was found but failed local format validation */
+  invalid?: boolean;
+  /** Human-readable explanation of the tier decision */
+  reason: string;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const ENV_VAR = "DEVORY_LICENSE_KEY";
+const LICENSE_FILE = path.join(".devory", "license");
+
+/**
+ * Minimum length for a key to pass local format validation.
+ * Keys will follow a `devory_<tier>_<random>` convention once the license
+ * service is built; this floor rejects obvious junk values in the meantime.
+ */
+const MIN_KEY_LENGTH = 16;
+
+// ---------------------------------------------------------------------------
+// Tier detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect the current license tier.
+ *
+ * @param factoryRoot  Absolute path to the factory workspace root.
+ *                     When omitted, file-based key detection is skipped.
+ */
+export function detectTier(factoryRoot?: string): LicenseInfo {
+  // 1. Environment variable
+  const envKey = process.env[ENV_VAR];
+  if (envKey !== undefined) {
+    return validateKey(envKey.trim(), "env");
+  }
+
+  // 2. .devory/license file
+  if (factoryRoot) {
+    const filePath = path.join(factoryRoot, LICENSE_FILE);
+    if (fs.existsSync(filePath)) {
+      const fileKey = fs.readFileSync(filePath, "utf-8").trim();
+      return validateKey(fileKey, "file");
+    }
+  }
+
+  // 3. No key — Core
+  return {
+    tier: "core",
+    reason: "No license key found — running on Core tier",
+  };
+}
+
+/**
+ * Validate a raw key string and return the corresponding LicenseInfo.
+ * Currently performs local format validation only.
+ * Network verification is a no-op stub until the license service exists.
+ */
+function validateKey(key: string, source: "env" | "file"): LicenseInfo {
+  if (!key || key.length < MIN_KEY_LENGTH) {
+    return {
+      tier: "core",
+      key,
+      source,
+      invalid: true,
+      reason: `License key from ${source === "env" ? "DEVORY_LICENSE_KEY" : ".devory/license"} is invalid (must be ≥ ${MIN_KEY_LENGTH} characters) — falling back to Core tier`,
+    };
+  }
+
+  // TODO: when the license service ships, verify the key here (once, cached
+  // locally in .devory/license-cache.json with an expiry timestamp).
+  return {
+    tier: "pro",
+    key,
+    source,
+    reason: `License key found via ${source === "env" ? "DEVORY_LICENSE_KEY" : ".devory/license"} — Pro tier active`,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Feature gating
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns true if the given Pro feature is enabled for the current tier.
+ * Call this at each Pro feature boundary instead of comparing tier directly.
+ */
+export function isFeatureEnabled(feature: ProFeature, info: LicenseInfo): boolean {
+  // All Pro features require Pro tier. Teams features would extend this check.
+  switch (feature) {
+    case "custom_rules":
+    case "baseline_overrides":
+    case "shared_doctrine":
+    case "pr_gates":
+      return info.tier === "pro";
+  }
+}
+
+/**
+ * Produce a one-line advisory message shown to Core users when they have a
+ * Pro-only field configured. Shown once per command invocation, not per file.
+ */
+export function tierGateMessage(feature: ProFeature): string {
+  const featureLabel: Record<ProFeature, string> = {
+    custom_rules: "custom_rules in devory.standards.yml",
+    baseline_overrides: "baseline overrides",
+    shared_doctrine: "shared doctrine",
+    pr_gates: "PR gates",
+  };
+  return (
+    `[devory] ${featureLabel[feature]} requires a Pro license — ` +
+    `set DEVORY_LICENSE_KEY or create .devory/license to upgrade. ` +
+    `This setting will be ignored on Core tier.`
+  );
+}

package/src/standards.ts

@@ -0,0 +1,283 @@
+/**
+ * packages/core/src/standards.ts
+ *
+ * Loads and types the devory.standards.yml configuration file.
+ *
+ * devory.standards.yml is the user-facing doctrine source — the structured
+ * definition of what "good" means for a given codebase. When present it takes
+ * precedence over the freeform brain/ markdown files.
+ *
+ * Entry points:
+ *   loadStandards(factoryRoot)          — load and parse the YAML file
+ *   serializeStandardsAsDoctrine(s)     — render as a string for AI context injection
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import { fileURLToPath } from "url";
+import { load as parseYaml } from "js-yaml";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// ---------------------------------------------------------------------------
+// Schema types
+// ---------------------------------------------------------------------------
+
+export interface StandardsStack {
+  language?: string;
+  framework?: string;
+  database?: string;
+}
+
+export interface StandardsTesting {
+  require_unit?: boolean;
+  require_integration?: boolean;
+  coverage_threshold?: number;
+  avoid_mocking?: string[];
+}
+
+export interface StandardsArchitecture {
+  pattern?: string;
+  max_file_lines?: number;
+  no_circular_deps?: boolean;
+}
+
+export interface StandardsCodeStyle {
+  no_any?: boolean;
+  prefer_explicit_over_clever?: boolean;
+}
+
+export interface StandardsDoctrine {
+  extends?: string;
+  testing?: StandardsTesting;
+  architecture?: StandardsArchitecture;
+  code_style?: StandardsCodeStyle;
+  /** Pro/Teams tier only — ignored on Core */
+  custom_rules?: string[];
+}
+
+export interface Standards {
+  version?: string;
+  stack?: StandardsStack;
+  doctrine?: StandardsDoctrine;
+}
+
+// ---------------------------------------------------------------------------
+// Source descriptor
+// ---------------------------------------------------------------------------
+
+export type StandardsSourceType = "yaml" | "brain" | "none";
+
+export interface StandardsSource {
+  type: StandardsSourceType;
+  /** Absolute path to devory.standards.yml, if found */
+  path?: string;
+}
+
+export interface LoadedStandards {
+  standards: Standards;
+  source: StandardsSource;
+}
+
+// ---------------------------------------------------------------------------
+// Loader
+// ---------------------------------------------------------------------------
+
+export const STANDARDS_FILENAME = "devory.standards.yml";
+
+/**
+ * Load devory.standards.yml from the factory root.
+ * Returns null standards and source type "none" when the file does not exist.
+ * Throws a descriptive error if the file exists but cannot be parsed.
+ */
+export function loadStandards(factoryRoot: string): LoadedStandards {
+  const filePath = path.join(factoryRoot, STANDARDS_FILENAME);
+
+  if (!fs.existsSync(filePath)) {
+    return { standards: {}, source: { type: "none" } };
+  }
+
+  const raw = fs.readFileSync(filePath, "utf-8");
+
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(raw);
+  } catch (err) {
+    throw new Error(
+      `devory: failed to parse ${STANDARDS_FILENAME}: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+
+  if (parsed === null || typeof parsed !== "object") {
+    throw new Error(`devory: ${STANDARDS_FILENAME} must be a YAML object, got: ${typeof parsed}`);
+  }
+
+  const user = parsed as Standards;
+  const extendsValue = (user as Standards & { extends?: string }).extends
+    ?? user.doctrine?.extends;
+
+  // Resolve extends chain if a bundled baseline is referenced
+  const standards = extendsValue
+    ? mergeStandards(loadBaseline(extendsValue), user)
+    : user;
+
+  return {
+    standards,
+    source: { type: "yaml", path: filePath },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Baseline resolver
+//
+// Maps "@devory/defaults/<name>" to the bundled YAML file shipped with
+// @devory/core. Users reference baselines via the `extends` field in
+// devory.standards.yml or within baseline files themselves.
+// ---------------------------------------------------------------------------
+
+const DEVORY_DEFAULTS_PREFIX = "@devory/defaults/";
+const DEFAULTS_DIR = path.join(__dirname, "defaults");
+
+const KNOWN_BASELINES: Record<string, string> = {
+  generic: "generic.yml",
+  "typescript-nextjs": "typescript-nextjs.yml",
+  "typescript-node": "typescript-node.yml",
+};
+
+/**
+ * Resolve an extends string to an absolute path.
+ * Returns null if the baseline is not a bundled Devory baseline or does not exist.
+ */
+export function resolveBaselinePath(extendsValue: string): string | null {
+  if (!extendsValue.startsWith(DEVORY_DEFAULTS_PREFIX)) return null;
+  const key = extendsValue.slice(DEVORY_DEFAULTS_PREFIX.length);
+  const filename = KNOWN_BASELINES[key];
+  if (!filename) return null;
+  return path.join(DEFAULTS_DIR, filename);
+}
+
+/**
+ * Load a bundled Devory baseline by its extends identifier.
+ * Recursively resolves the baseline's own extends chain (e.g. typescript-nextjs → generic).
+ * Returns an empty Standards object if the baseline cannot be found.
+ */
+export function loadBaseline(extendsValue: string): Standards {
+  const filePath = resolveBaselinePath(extendsValue);
+  if (!filePath || !fs.existsSync(filePath)) return {};
+
+  const raw = fs.readFileSync(filePath, "utf-8");
+  const parsed = parseYaml(raw);
+  if (!parsed || typeof parsed !== "object") return {};
+
+  const baseline = parsed as Standards & { extends?: string };
+  const parentExtends = baseline.extends;
+
+  if (parentExtends) {
+    const parent = loadBaseline(parentExtends);
+    return mergeStandards(parent, baseline);
+  }
+
+  return baseline as Standards;
+}
+
+/**
+ * Merge two Standards objects — base values are overridden by overrides.
+ * Only one level of nesting is merged (stack, doctrine sub-objects).
+ */
+export function mergeStandards(base: Standards, overrides: Standards): Standards {
+  return {
+    version: overrides.version ?? base.version,
+    stack: overrides.stack || base.stack
+      ? { ...base.stack, ...overrides.stack }
+      : undefined,
+    doctrine: overrides.doctrine || base.doctrine
+      ? {
+          ...base.doctrine,
+          ...overrides.doctrine,
+          testing: overrides.doctrine?.testing || base.doctrine?.testing
+            ? { ...base.doctrine?.testing, ...overrides.doctrine?.testing }
+            : undefined,
+          architecture: overrides.doctrine?.architecture || base.doctrine?.architecture
+            ? { ...base.doctrine?.architecture, ...overrides.doctrine?.architecture }
+            : undefined,
+          code_style: overrides.doctrine?.code_style || base.doctrine?.code_style
+            ? { ...base.doctrine?.code_style, ...overrides.doctrine?.code_style }
+            : undefined,
+        }
+      : undefined,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Doctrine serializer
+//
+// Renders a Standards object as a human-readable markdown-ish string
+// suitable for injection into an AI worker's context alongside other doctrine.
+// ---------------------------------------------------------------------------
+
+export function serializeStandardsAsDoctrine(standards: Standards): string {
+  const lines: string[] = ["# Engineering Standards (devory.standards.yml)", ""];
+
+  const { stack, doctrine } = standards;
+
+  if (stack) {
+    lines.push("## Stack");
+    if (stack.language) lines.push(`- Language: ${stack.language}`);
+    if (stack.framework) lines.push(`- Framework: ${stack.framework}`);
+    if (stack.database) lines.push(`- Database: ${stack.database}`);
+    lines.push("");
+  }
+
+  if (doctrine) {
+    if (doctrine.extends) {
+      lines.push(`## Baseline`);
+      lines.push(`Extends: ${doctrine.extends}`);
+      lines.push("");
+    }
+
+    if (doctrine.testing) {
+      lines.push("## Testing Standards");
+      const t = doctrine.testing;
+      if (t.require_unit !== undefined)
+        lines.push(`- Unit tests required: ${t.require_unit}`);
+      if (t.require_integration !== undefined)
+        lines.push(`- Integration tests required: ${t.require_integration}`);
+      if (t.coverage_threshold !== undefined)
+        lines.push(`- Coverage threshold: ${t.coverage_threshold}%`);
+      if (t.avoid_mocking?.length)
+        lines.push(`- Avoid mocking: ${t.avoid_mocking.join(", ")}`);
+      lines.push("");
+    }
+
+    if (doctrine.architecture) {
+      lines.push("## Architecture Standards");
+      const a = doctrine.architecture;
+      if (a.pattern) lines.push(`- Pattern: ${a.pattern}`);
+      if (a.max_file_lines !== undefined)
+        lines.push(`- Max file lines: ${a.max_file_lines}`);
+      if (a.no_circular_deps !== undefined)
+        lines.push(`- No circular dependencies: ${a.no_circular_deps}`);
+      lines.push("");
+    }
+
+    if (doctrine.code_style) {
+      lines.push("## Code Style Standards");
+      const cs = doctrine.code_style;
+      if (cs.no_any !== undefined) lines.push(`- No \`any\` type: ${cs.no_any}`);
+      if (cs.prefer_explicit_over_clever !== undefined)
+        lines.push(`- Prefer explicit over clever: ${cs.prefer_explicit_over_clever}`);
+      lines.push("");
+    }
+
+    if (doctrine.custom_rules?.length) {
+      lines.push("## Custom Rules");
+      for (const rule of doctrine.custom_rules) {
+        lines.push(`- ${rule}`);
+      }
+      lines.push("");
+    }
+  }
+
+  return lines.join("\n").trimEnd();
+}