@flowmark/core-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 centimani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+# FlowMark-core
+
+Core CLI for FlowMark v0.1.
+
+## Install (npm)
+
+```bash
+npm install @flowmark/core-cli
+```
+
+## Usage
+
+```bash
+flowmark validate path/to/file.md
+cat path/to/file.md | flowmark validate
+flowmark parse path/to/file.md
+flowmark lint path/to/file.md
+```
+
+## Options
+
+- `--strict` : strict mode
+- `--lenient` : lenient mode (default)
+- `--stdin` : read from STDIN even if file is provided
+- `--version`
+- `--help`
+
+## Docker
+
+Image: `ghcr.io/centimani/flowmark-core-cli`
+
+```bash
+docker run --rm -v "$(pwd)":/work -w /work ghcr.io/centimani/flowmark-core-cli validate path/to/file.md
+cat path/to/file.md | docker run --rm -i -v "$(pwd)":/work -w /work ghcr.io/centimani/flowmark-core-cli validate --stdin
+```
+
+## Test Samples (MVP)
+
+```bash
+node bin/flowmark.js validate docs/dev/v0.1/samples/minimal.md
+node bin/flowmark.js validate docs/dev/v0.1/samples/invalid-duplicate-header.md
+node bin/flowmark.js validate docs/dev/v0.1/samples/invalid-no-item.md
+node bin/flowmark.js validate docs/dev/v0.1/samples/invalid-status.md
+node bin/flowmark.js validate docs/dev/v0.1/samples/invalid-coverage.md
+node bin/flowmark.js validate docs/dev/v0.1/samples/invalid-yaml.md
+node bin/flowmark.js validate docs/dev/v0.1/samples/lenient-unexpected.md
+```
+
+Note: If `E_YAML_PARSE` occurs, derived errors/warnings (e.g. `E_ITEM_NONE`, `W_REGISTRY_MISSING`) are suppressed.
+
+## Strict vs Lenient (Example)
+
+```bash
+node bin/flowmark.js validate docs/dev/v0.1/samples/lenient-unexpected.md
+node bin/flowmark.js validate --strict docs/dev/v0.1/samples/lenient-unexpected.md
+```
+
+In `lenient`, unexpected items are warnings (`W_UNEXPECTED_ITEM`).  
+In `strict`, they become errors (`E_UNEXPECTED_ITEM`).
+
+## Unknown Keys Warning
+
+Unknown keys are allowed but produce `W_UNKNOWN_KEYS` warnings.
+
+## npm pack (Publish Check)
+
+```bash
+npm pack
+tar -tf flowmark-core-cli-0.1.0.tgz
+```
+
+Check that `bin/`, `src/`, `README.md`, and `LICENSE` are included.

package/bin/flowmark.js

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const { parseFlowmark, toDocument } = require('../src/parser/flowmark');
+const { validateDocument, lintDocument } = require('../src/validator/validate');
+
+function printHelp() {
+  const msg = `FlowMark CLI (v0.1)
+
+Usage:
+  flowmark validate <file>
+  flowmark parse <file>
+  flowmark lint <file>
+  cat file.md | flowmark validate
+
+Options:
+  --strict      Use strict mode
+  --lenient     Use lenient mode (default)
+  --stdin       Read from STDIN even if a file is provided
+  --version     Print version
+  --help        Show help
+`;
+  process.stdout.write(msg);
+}
+
+function readVersion() {
+  const pkgPath = path.resolve(__dirname, '..', 'package.json');
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+  return pkg.version || '0.0.0';
+}
+
+function parseArgs(argv) {
+  const opts = {
+    mode: 'lenient',
+    stdin: false,
+    help: false,
+    version: false
+  };
+  let command = null;
+  let file = null;
+
+  for (const arg of argv) {
+    if (arg === '--help' || arg === '-h') {
+      opts.help = true;
+    } else if (arg === '--version') {
+      opts.version = true;
+    } else if (arg === '--strict') {
+      opts.mode = 'strict';
+    } else if (arg === '--lenient') {
+      opts.mode = 'lenient';
+    } else if (arg === '--stdin') {
+      opts.stdin = true;
+    } else if (!command) {
+      command = arg;
+    } else if (!file) {
+      file = arg;
+    } else {
+      // ignore extra args for now
+    }
+  }
+
+  return { command, file, opts };
+}
+
+function readInput({ file, stdin }) {
+  if (stdin) {
+    return fs.readFileSync(0, 'utf8');
+  }
+  if (file) {
+    return fs.readFileSync(file, 'utf8');
+  }
+  if (process.stdin.isTTY) {
+    throw new Error('No input provided. Pass a file or pipe STDIN.');
+  }
+  return fs.readFileSync(0, 'utf8');
+}
+
+function run() {
+  const { command, file, opts } = parseArgs(process.argv.slice(2));
+
+  if (opts.version) {
+    process.stdout.write(readVersion() + '\n');
+    return process.exit(0);
+  }
+
+  if (opts.help || !command) {
+    printHelp();
+    return process.exit(opts.help ? 0 : 2);
+  }
+
+  if (command !== 'validate') {
+    if (command !== 'parse' && command !== 'lint') {
+      process.stderr.write(`Unknown command: ${command}\n`);
+      printHelp();
+      return process.exit(2);
+    }
+  }
+
+  let input;
+  try {
+    input = readInput({ file, stdin: opts.stdin });
+  } catch (err) {
+    process.stderr.write(String(err.message || err) + '\n');
+    return process.exit(2);
+  }
+
+  const parsed = parseFlowmark(input);
+
+  if (command === 'parse') {
+    const output = {
+      document: toDocument(parsed),
+      errors: parsed.errors || []
+    };
+    process.stdout.write(JSON.stringify(output, null, 2) + '\n');
+    return process.exit(output.errors.length > 0 ? 2 : 0);
+  }
+
+  if (command === 'lint') {
+    const result = lintDocument(parsed, { mode: opts.mode });
+    const output = {
+      mode: opts.mode,
+      errors: result.errors,
+      warnings: result.warnings
+    };
+    process.stdout.write(JSON.stringify(output, null, 2) + '\n');
+    if (output.errors.length > 0) return process.exit(2);
+    if (output.warnings.length > 0) return process.exit(1);
+    return process.exit(0);
+  }
+
+  const result = validateDocument(parsed, { mode: opts.mode });
+  const output = {
+    mode: opts.mode,
+    errors: result.errors,
+    warnings: result.warnings
+  };
+  process.stdout.write(JSON.stringify(output, null, 2) + '\n');
+
+  if (output.errors.length > 0) {
+    return process.exit(2);
+  }
+  if (output.warnings.length > 0) {
+    return process.exit(1);
+  }
+  return process.exit(0);
+}
+
+run();

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@flowmark/core-cli",
+  "version": "0.1.0",
+  "description": "FlowMark core CLI",
+  "private": false,
+  "keywords": [
+    "flowmark",
+    "cli",
+    "validator"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/centimani/flowmark-core.git"
+  },
+  "bugs": {
+    "url": "https://github.com/centimani/flowmark-core/issues"
+  },
+  "homepage": "https://github.com/centimani/flowmark-core#readme",
+  "license": "MIT",
+  "type": "commonjs",
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "flowmark": "bin/flowmark.js"
+  },
+  "dependencies": {
+    "yaml": "^2.4.5"
+  }
+}

package/src/parser/flowmark.js

@@ -0,0 +1,88 @@
+const YAML = require('yaml');
+const { scanFencedBlocks } = require('./scan');
+
+const INFO_MAP = {
+  'yaml flowmark': 'header',
+  'yaml flowmark-section': 'section',
+  'yaml flowmark-item': 'item',
+  'yaml flowmark-registry': 'registry'
+};
+
+function parseYamlBlock(block) {
+  const doc = YAML.parseDocument(block.content, { prettyErrors: false });
+  if (doc.errors && doc.errors.length > 0) {
+    const err = doc.errors[0];
+    let location = null;
+    if (err.linePos && err.linePos.start && typeof err.linePos.start.line === 'number') {
+      const base = block.startLine + 1;
+      const start = err.linePos.start.line;
+      const end = err.linePos.end && typeof err.linePos.end.line === 'number'
+        ? err.linePos.end.line
+        : start;
+      location = {
+        start_line: base + start - 1,
+        end_line: base + end - 1
+      };
+    }
+    return {
+      error: {
+        code: 'E_YAML_PARSE',
+        message: `YAML parse error: ${err.message}`,
+        location
+      }
+    };
+  }
+
+  return { data: doc.toJSON() };
+}
+
+function parseFlowmark(text) {
+  const blocks = scanFencedBlocks(text);
+  const result = {
+    headers: [],
+    sections: [],
+    items: [],
+    registries: [],
+    errors: []
+  };
+
+  for (const block of blocks) {
+    const type = INFO_MAP[block.info];
+    if (!type) {
+      continue;
+    }
+
+    const parsed = parseYamlBlock(block);
+    if (parsed.error) {
+      result.errors.push(parsed.error);
+      continue;
+    }
+
+    const entry = {
+      data: parsed.data,
+      location: { start_line: block.startLine, end_line: block.endLine }
+    };
+
+    if (type === 'header') result.headers.push(entry);
+    if (type === 'section') result.sections.push(entry);
+    if (type === 'item') result.items.push(entry);
+    if (type === 'registry') result.registries.push(entry);
+  }
+
+  return result;
+}
+
+function toDocument(parsed) {
+  const header = parsed.headers[0]
+    ? { ...parsed.headers[0].data, location: parsed.headers[0].location }
+    : null;
+  const sections = parsed.sections.map((s) => ({ ...s.data, location: s.location }));
+  const items = parsed.items.map((i) => ({ ...i.data, location: i.location }));
+  const registry = parsed.registries[0]
+    ? { ...parsed.registries[0].data, location: parsed.registries[0].location }
+    : null;
+
+  return { header, sections, items, registry };
+}
+
+module.exports = { parseFlowmark, toDocument };

package/src/parser/scan.js

@@ -0,0 +1,45 @@
+function scanFencedBlocks(text) {
+  const lines = text.split(/\r?\n/);
+  const blocks = [];
+
+  let inFence = false;
+  let info = '';
+  let startLine = 0;
+  let contentLines = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    if (!inFence) {
+      const startMatch = line.match(/^(\s*)```(.*)$/);
+      if (startMatch) {
+        inFence = true;
+        info = (startMatch[2] || '').trim();
+        startLine = i + 1;
+        contentLines = [];
+      }
+      continue;
+    }
+
+    const endMatch = line.match(/^(\s*)```\s*$/);
+    if (endMatch) {
+      const endLine = i + 1;
+      blocks.push({
+        info,
+        content: contentLines.join('\n'),
+        startLine,
+        endLine
+      });
+      inFence = false;
+      info = '';
+      startLine = 0;
+      contentLines = [];
+    } else {
+      contentLines.push(line);
+    }
+  }
+
+  return blocks;
+}
+
+module.exports = { scanFencedBlocks };

package/src/validator/validate.js

@@ -0,0 +1,301 @@
+const ALLOWED_STATUS = new Set(['todo', 'done', 'skipped', 'blocked']);
+
+const ALLOWED_KEYS = {
+  header: new Set(['id', 'title', 'version', 'status', 'created_at', 'inputs']),
+  section: new Set(['id', 'scope', 'notes']),
+  item: new Set(['id', 'status', 'refs', 'batch']),
+  registry: new Set(['expected_items'])
+};
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.trim() !== '';
+}
+
+function addSchemaError(errors, message, location) {
+  errors.push({
+    code: 'E_SCHEMA_INVALID',
+    message,
+    location: location || null
+  });
+}
+
+function addUnknownKeyWarnings(kind, entry, warnings) {
+  if (!entry || !entry.data || typeof entry.data !== 'object' || Array.isArray(entry.data)) {
+    return;
+  }
+  const allowed = ALLOWED_KEYS[kind];
+  if (!allowed) return;
+  const unknown = Object.keys(entry.data).filter((k) => !allowed.has(k));
+  if (unknown.length === 0) return;
+  warnings.push({
+    code: 'W_UNKNOWN_KEYS',
+    message: `Unknown keys in ${kind}: ${unknown.join(', ')}`,
+    location: entry.location || null
+  });
+}
+
+function validateDocument(parsed, { mode }) {
+  const errors = [...(parsed.errors || [])];
+  const warnings = [];
+  const hasParseError = errors.some((e) => e && e.code === 'E_YAML_PARSE');
+
+  if (parsed.headers.length === 0) {
+    errors.push({
+      code: 'E_HEADER_MISSING',
+      message: 'Header block is missing.',
+      location: null
+    });
+  } else if (parsed.headers.length > 1) {
+    for (let i = 1; i < parsed.headers.length; i++) {
+      errors.push({
+        code: 'E_HEADER_DUPLICATE',
+        message: 'Header block is duplicated.',
+        location: parsed.headers[i].location || null
+      });
+    }
+  }
+
+  if (parsed.headers.length > 0) {
+    const header = parsed.headers[0];
+    const data = header.data;
+    if (!data || typeof data !== 'object' || Array.isArray(data)) {
+      addSchemaError(errors, 'Header block must be a mapping.', header.location);
+    } else {
+      if (!isNonEmptyString(data.id)) {
+        addSchemaError(errors, 'Header id is required.', header.location);
+      }
+      if (!isNonEmptyString(data.title)) {
+        addSchemaError(errors, 'Header title is required.', header.location);
+      }
+      if (!isNonEmptyString(data.version)) {
+        addSchemaError(errors, 'Header version must be a non-empty string.', header.location);
+      }
+    }
+  }
+
+  if (!hasParseError && parsed.items.length === 0) {
+    errors.push({
+      code: 'E_ITEM_NONE',
+      message: 'No item blocks found.',
+      location: null
+    });
+  }
+
+  const itemIds = new Set();
+  for (const item of parsed.items) {
+    if (hasParseError) break;
+    const data = item.data;
+    if (!data || typeof data !== 'object' || Array.isArray(data)) {
+      addSchemaError(errors, 'Item block must be a mapping.', item.location);
+      continue;
+    }
+    const id = data.id;
+    const status = data.status;
+
+    if (isNonEmptyString(id)) {
+      if (itemIds.has(id)) {
+        errors.push({
+          code: 'E_ITEM_ID_DUPLICATE',
+          message: `Duplicate item id: ${id}`,
+          location: item.location || null
+        });
+      } else {
+        itemIds.add(id);
+      }
+    } else {
+      addSchemaError(errors, 'Item id is required.', item.location);
+    }
+
+    if (!isNonEmptyString(status)) {
+      addSchemaError(errors, 'Item status is required.', item.location);
+    } else if (!ALLOWED_STATUS.has(status)) {
+      errors.push({
+        code: 'E_ITEM_STATUS_INVALID',
+        message: `Invalid item status: ${status}`,
+        location: item.location || null
+      });
+    }
+
+    addUnknownKeyWarnings('item', item, warnings);
+  }
+
+  for (const section of parsed.sections) {
+    addUnknownKeyWarnings('section', section, warnings);
+  }
+  for (const header of parsed.headers) {
+    addUnknownKeyWarnings('header', header, warnings);
+  }
+
+  if (!hasParseError && parsed.registries.length === 0) {
+    warnings.push({
+      code: 'W_REGISTRY_MISSING',
+      message: 'Registry block is missing.',
+      location: null
+    });
+  } else if (parsed.registries.length > 1) {
+    for (let i = 1; i < parsed.registries.length; i++) {
+      errors.push({
+        code: 'E_REGISTRY_DUPLICATE',
+        message: 'Registry block is duplicated.',
+        location: parsed.registries[i].location || null
+      });
+    }
+  }
+
+  if (!hasParseError && parsed.registries.length > 0) {
+    const registry = parsed.registries[0];
+    addUnknownKeyWarnings('registry', registry, warnings);
+
+    const expected = registry.data && typeof registry.data === 'object' && !Array.isArray(registry.data)
+      ? registry.data.expected_items
+      : null;
+
+    if (!Array.isArray(expected)) {
+      addSchemaError(errors, 'Registry expected_items must be an array.', registry.location);
+    } else {
+      const expectedSet = new Set();
+      const duplicates = new Set();
+      for (const id of expected) {
+        if (expectedSet.has(id)) duplicates.add(id);
+        expectedSet.add(id);
+      }
+      if (duplicates.size > 0) {
+        errors.push({
+          code: 'E_REGISTRY_DUPLICATE',
+          message: `Duplicate registry ids: ${Array.from(duplicates).join(', ')}`,
+          location: registry.location || null
+        });
+      }
+
+      const missing = Array.from(expectedSet).filter((id) => !itemIds.has(id));
+      const unexpected = Array.from(itemIds).filter((id) => !expectedSet.has(id));
+
+      if (missing.length > 0) {
+        errors.push({
+          code: 'E_COVERAGE_MISSING',
+          message: `Missing items: ${missing.join(', ')}`,
+          location: registry.location || null
+        });
+      }
+
+      if (unexpected.length > 0) {
+        if (mode === 'strict') {
+          errors.push({
+            code: 'E_UNEXPECTED_ITEM',
+            message: `Unexpected items: ${unexpected.join(', ')}`,
+            location: registry.location || null
+          });
+        } else {
+          warnings.push({
+            code: 'W_UNEXPECTED_ITEM',
+            message: `Unexpected items: ${unexpected.join(', ')}`,
+            location: registry.location || null
+          });
+        }
+      }
+    }
+  }
+
+  const sectionIds = new Set();
+  for (const section of parsed.sections) {
+    const data = section.data;
+    const id = data && typeof data === 'object' && !Array.isArray(data) ? data.id : null;
+    if (typeof id === 'string' && id.trim() !== '') {
+      if (sectionIds.has(id)) {
+        warnings.push({
+          code: 'W_SECTION_ID_DUPLICATE',
+          message: `Duplicate section id: ${id}`,
+          location: section.location || null
+        });
+      } else {
+        sectionIds.add(id);
+      }
+    }
+  }
+
+  return { errors, warnings };
+}
+
+function lintDocument(parsed, { mode }) {
+  const errors = [...(parsed.errors || [])];
+  const warnings = [];
+  const hasParseError = errors.some((e) => e && e.code === 'E_YAML_PARSE');
+  if (hasParseError) {
+    return { errors, warnings };
+  }
+
+  const itemIds = new Set();
+  for (const item of parsed.items) {
+    const data = item.data;
+    if (data && typeof data === 'object' && !Array.isArray(data) && isNonEmptyString(data.id)) {
+      itemIds.add(data.id);
+    }
+    addUnknownKeyWarnings('item', item, warnings);
+  }
+  for (const section of parsed.sections) {
+    addUnknownKeyWarnings('section', section, warnings);
+  }
+  for (const header of parsed.headers) {
+    addUnknownKeyWarnings('header', header, warnings);
+  }
+
+  if (parsed.registries.length === 0) {
+    warnings.push({
+      code: 'W_REGISTRY_MISSING',
+      message: 'Registry block is missing.',
+      location: null
+    });
+  }
+
+  if (parsed.registries.length > 0) {
+    const registry = parsed.registries[0];
+    addUnknownKeyWarnings('registry', registry, warnings);
+    const expected = registry.data && typeof registry.data === 'object' && !Array.isArray(registry.data)
+      ? registry.data.expected_items
+      : null;
+    if (Array.isArray(expected)) {
+      const expectedSet = new Set();
+      const duplicates = new Set();
+      for (const id of expected) {
+        if (expectedSet.has(id)) duplicates.add(id);
+        expectedSet.add(id);
+      }
+      if (duplicates.size > 0) {
+        warnings.push({
+          code: 'W_REGISTRY_DUPLICATE',
+          message: `Duplicate registry ids: ${Array.from(duplicates).join(', ')}`,
+          location: registry.location || null
+        });
+      }
+      const unexpected = Array.from(itemIds).filter((id) => !expectedSet.has(id));
+      if (unexpected.length > 0) {
+        warnings.push({
+          code: 'W_UNEXPECTED_ITEM',
+          message: `Unexpected items: ${unexpected.join(', ')}`,
+          location: registry.location || null
+        });
+      }
+    }
+  }
+
+  const sectionIds = new Set();
+  for (const section of parsed.sections) {
+    const data = section.data;
+    const id = data && typeof data === 'object' && !Array.isArray(data) ? data.id : null;
+    if (isNonEmptyString(id)) {
+      if (sectionIds.has(id)) {
+        warnings.push({
+          code: 'W_SECTION_ID_DUPLICATE',
+          message: `Duplicate section id: ${id}`,
+          location: section.location || null
+        });
+      } else {
+        sectionIds.add(id);
+      }
+    }
+  }
+
+  return { errors, warnings };
+}
+
+module.exports = { validateDocument, lintDocument };