@josfox/jos 0.2.1 → 3.1.0

package/LICENSE

@@ -1 +1,20 @@
-MIT
+MIT License
+
+Copyright (c) 2025 JOSFOX
+
+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 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/NOTICE

@@ -0,0 +1,4 @@
+JOSFOX `.jos` Specification v0.3.1 — Community Edition
+Spec: CC BY 4.0 (attribution required). Implementation code: MIT.
+NO WARRANTY. Users must implement their own security and operational safeguards.
+Repo (spec): https://github.com/josfox-ai/jos-format-spec

package/README.md

@@ -1,2 +1,50 @@
-# @josfox/jos v0.2.1
-Short-name CLI. Supports --version/--help and .jos export.
+# @josfox/jos — v3.1 (Community Runtime)
+
+**Spec-aligned**: tied to **JOSFOX `.jos` v0.3.1** (Experimental, Community Edition).  
+Implements: **validate · run · serve · pack · publish · doc · test · lint** (community scope).
+
+> **License**: MIT (code). The **spec** is **CC BY 4.0** — *attribution required*.  
+> **No Warranty**: This software is provided **AS IS**. Users must implement their own safeguards.
+
+**Repo (spec):** https://github.com/josfox-ai/jos-format-spec
+
+## Install
+```bash
+npm i -g @josfox/jos
+```
+
+## Commands
+- `jos validate <file>` — validate against v0.3.1 schema and resolve `$extends/$imports`.
+- `jos run <file>` — execute a `task` or `pipeline` (shell/node; http/forge/ai are community stubs).
+- `jos serve <file>` — run the declared `devServer` for local testing.
+- `jos pack <file> --out dist.json` — package resolved artifact (JSON).
+- `jos publish <file>` — placeholder for JOSFOX.cloud Forge.
+- `jos doc <file> --out README.md` — generate quick docs from `.jos`.
+- `jos test <file>` — run `checks[]` (basic assertions).
+- `jos lint <path>` — basic spec lint.
+
+## Eval hooks (fight evaluation blindness)
+Declare in `.jos`:
+```json
+{
+  "evaluation": {
+    "contract": "stars_1_5",
+    "feedbackEndpoint": "https://example.com/eval",
+    "authToken": "REPLACE_ME",
+    "context": {"project": "landing"}
+  }
+}
+```
+Then call:
+```bash
+jos run file.jos --eval.stars 5 --eval.notes "LGTM" --eval.context '{"actor":"human"}'
+```
+
+## Email privacy
+- Use org-level maintainer (e.g., `oss@josfox.mx`) and hide personal email in npm profile.
+- Use GitHub noreply for commits (Settings → Emails → “Keep my email addresses private”).
+
+## License
+- Code: **MIT**  
+- Spec: **CC BY 4.0** (attribution required)  
+- See `LICENSE`, `NOTICE`, and `THIRD_PARTY_NOTICES.md`.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,11 @@
+# Third-Party Notices for @josfox/jos
+
+This project uses open-source components. We thank the open-source community.
+
+## ajv (MIT)
+https://github.com/ajv-validator/ajv
+
+## yargs (MIT)
+https://github.com/yargs/yargs
+
+> Include full license texts if your distribution bundles these libraries.

package/bin/jos.js

@@ -1,47 +1,36 @@
 #!/usr/bin/env node
-const fs = require('fs');
-const path = require('path');
-const { DEFAULT_SPEC, asConsole } = require('../lib/spec');
-const VERSION = "0.2.1";
-function printBanner(){ console.log(`JOSFOX CLI v${VERSION}`); }
-function printHelp(){ printBanner(); console.log(`
-Usage:
-  jos [command] [options]
+import { hideBin } from 'yargs/helpers'; import yargs from 'yargs'; import fs from 'node:fs';
+import { validate } from '../lib/validate.js'; import { resolveJos } from '../lib/resolve.js';
+import { run } from '../lib/run.js'; import { serve } from '../lib/serve.js';
 
-Commands:
-  help                   Show help
-  version                Print version
-  init <name>            Scaffold a starter folder with spec.jos.json
-  export --format FMT    Export current spec (FMT: jos|console)
-  run [--mode value]     Example
+function writeJSON(p, data){ fs.writeFileSync(p, JSON.stringify(data, null, 2), 'utf8'); }
 
-Flags:
-  -h, --help             Show help
-  -v, --version          Print version
-`); }
-function main(){
-  const argv = process.argv.slice(2);
-  if (argv.includes('--version') || argv.includes('-v')) { console.log(VERSION); return; }
-  if (argv.includes('--help') || argv.includes('-h')) { printHelp(); return; }
-  const cmd = (argv[0] || 'help').toLowerCase(); const rest = argv.slice(1);
-  if (cmd === 'help' || cmd === '?') return printHelp();
-  if (cmd === 'version') return console.log(VERSION);
-  if (cmd === 'init') {
-    const name = rest[0]; if (!name) return (console.error('Provide a name: jos init <name>'), process.exit(1));
-    const dir = path.resolve(process.cwd(), name); if (!fs.existsSync(dir)) fs.mkdirSync(dir,{recursive:true});
-    fs.writeFileSync(path.join(dir,'spec.jos.json'), JSON.stringify(DEFAULT_SPEC,null,2));
-    console.log(`Initialized ${dir} with spec.jos.json`); return;
-  }
-  if (cmd === 'export') {
-    const idx = rest.indexOf('--format'); let fmt = 'jos';
-    if (idx >= 0 && rest[idx+1]) fmt = String(rest[idx+1]).toLowerCase();
-    if (fmt === 'console') console.log(asConsole(DEFAULT_SPEC)); else console.log(JSON.stringify(DEFAULT_SPEC,null,2));
-    return;
-  }
-  if (cmd === 'run') {
-    const m = rest.indexOf('--mode'); const mode = (m>=0 && rest[m+1]) ? rest[m+1] : 'default';
-    console.log(`Running in mode: ${mode}`); return;
-  }
-  printHelp();
-}
-main();
+yargs(hideBin(process.argv))
+  .scriptName('jos')
+  .command('validate <file>', 'Validate .jos v0.3.1', y=> y.positional('file',{type:'string'}), argv=>{
+    const res = validate(argv.file); if (!res.ok) { console.error('Schema errors:', res.errors); process.exit(1); } console.log('OK ✅');
+  })
+  .command('run <file>', 'Run task/pipeline', y=> y.positional('file',{type:'string'}), async argv=>{
+    const { doc } = validate(argv.file); const flags={}; for (const [k,v] of Object.entries(argv)) if (k.startsWith('eval.')) flags[k]=v;
+    const code = await run(doc, flags); process.exit(code);
+  })
+  .command('serve <file>', 'Run dev server', y=> y.positional('file',{type:'string'}), async argv=>{
+    const doc = resolveJos(argv.file); await serve(doc);
+  })
+  .command('doc <file> --out <out>', 'Generate docs', y=> y.positional('file',{type:'string'}).option('out',{type:'string', demandOption:true}), argv=>{
+    const { doc } = validate(argv.file); const tasks=(doc.tasks||[]).map(t=>`- **${t.id}** \`${t.runner}${t.action?':'+t.action:''}\``).join('\n');
+    const md = `# ${doc.name}\n\nSchema: ${doc.schema}\n\n## Tasks\n${tasks}\n`; fs.writeFileSync(argv.out, md, 'utf8'); console.log(`Doc written to ${argv.out}`);
+  })
+  .command('pack <file> --out <out>', 'Pack resolved JSON', y=> y.positional('file',{type:'string'}).option('out',{type:'string', demandOption:true}), argv=>{
+    const doc = resolveJos(argv.file); writeJSON(argv.out, doc); console.log(`Packed to ${out}`);
+  })
+  .command('publish <file>', 'Publish (stub)', y=> y.positional('file',{type:'string'}), argv=>{
+    console.warn('[stub] Forge publish not implemented in community build');
+  })
+  .command('test <file>', 'Run basic checks (stub)', y=> y.positional('file',{type:'string'}), argv=>{
+    console.warn('[stub] checks TBD');
+  })
+  .command('lint <path>', 'Lint (stub)', y=> y.positional('path',{type:'string'}), argv=>{
+    console.warn('[stub] lint TBD');
+  })
+  .demandCommand(1).help().parse();

package/examples/env-check.json

@@ -0,0 +1,39 @@
+{
+  "schema": "jos.v0.3.1",
+  "id": "tools/envCheck",
+  "name": "Env Check (masked)",
+  "version": "0.3.1",
+  "kind": "task",
+  "inputs": {
+    "vars": [
+      "NODE_ENV",
+      "PORT"
+    ],
+    "mask": [
+      "API_KEY",
+      "TOKEN"
+    ]
+  },
+  "envMap": {
+    "VARS": "inputs.vars",
+    "MASK": "inputs.mask"
+  },
+  "tasks": [
+    {
+      "id": "echo",
+      "runner": "shell",
+      "script": {
+        "shell": "bash",
+        "body": "missing=0; echo '\ud83d\udd0e Checking\u2026'; for v in $VARS; do val=$(printenv \"$v\"); if [ -z \"$val\" ]; then echo \"\u274c $v\"; missing=1; else if echo \"$MASK\" | tr ' ' '\\n' | grep -qx \"$v\"; then masked=$(printf '%s' \"$val\" | sed -E 's/.(?=.{4})/*/g'); echo \"\u2705 $v=$masked\"; else echo \"\u2705 $v=$val\"; fi; fi; done; [ $missing -eq 0 ] || exit 2"
+      }
+    }
+  ],
+  "evaluation": {
+    "contract": "stars_1_5",
+    "feedbackEndpoint": "https://example.com/eval",
+    "authToken": "REPLACE_ME",
+    "context": {
+      "task": "env-check"
+    }
+  }
+}

package/lib/resolve.js

@@ -0,0 +1,32 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function loadJSON(p) { return JSON.parse(fs.readFileSync(p, 'utf8')); }
+function isAbs(p){ return path.isAbsolute(p) || p.startsWith('http://') || p.startsWith('https://'); }
+export function resolvePath(base, rel) { return isAbs(rel) ? rel : path.join(path.dirname(base), rel); }
+export function deepMerge(a, b) {
+  if (Array.isArray(a) && Array.isArray(b)) return [...a, ...b];
+  if (a && typeof a === 'object' && b && typeof b === 'object') {
+    const out = { ...a };
+    for (const k of Object.keys(b)) out[k] = deepMerge(a[k], b[k]);
+    return out;
+  }
+  return b === undefined ? a : b;
+}
+export function resolveJos(entry) {
+  function _res(file) {
+    const doc = loadJSON(file);
+    let acc = { ...doc };
+    if (doc.$extends) {
+      const base = resolvePath(file, doc.$extends);
+      acc = deepMerge(_res(base), acc);
+      delete acc.$extends;
+    }
+    if (doc.$imports) {
+      for (const imp of doc.$imports) acc = deepMerge(_res(resolvePath(file, imp)), acc);
+      delete acc.$imports;
+    }
+    return acc;
+  }
+  return _res(entry);
+}

package/lib/run.js

@@ -0,0 +1,43 @@
+import { spawn } from 'node:child_process';
+import http from 'node:http'; import https from 'node:https';
+
+function postJSON(url, token, payload) {
+  const u = new URL(url);
+  const data = Buffer.from(JSON.stringify(payload));
+  const isHttps = u.protocol === 'https:';
+  const opts = { hostname: u.hostname, port: u.port || (isHttps ? 443 : 80),
+    path: u.pathname + (u.search || ''), method: 'POST',
+    headers: { 'content-type': 'application/json', 'content-length': data.length, ...(token ? {'authorization': `Bearer ${token}`} : {}) } };
+  const agent = isHttps ? https : http;
+  return new Promise((resolve, reject) => {
+    const req = agent.request(opts, res => { let body=''; res.on('data', c=> body+=c); res.on('end', ()=> resolve({ status: res.statusCode, body })); });
+    req.on('error', reject); req.write(data); req.end();
+  });
+}
+
+export async function run(doc, flags={}) {
+  const env = { ...process.env };
+  if (doc.envMap) for (const [k,v] of Object.entries(doc.envMap)) {
+    let val = v; if (typeof v === 'string' && v.startsWith('inputs.')) { const key = v.split('.').slice(1).join('.'); val = doc.inputs?.[key]; }
+    if (Array.isArray(val)) val = val.join(' '); env[k] = val;
+  }
+  let code = 0;
+  for (const t of (doc.tasks||[])) {
+    if (t.runner === 'shell') {
+      const sh = t.script?.shell || 'bash'; const body = t.script?.body || '';
+      const child = spawn(sh, ['-lc', body], { stdio: 'inherit', env });
+      code = await new Promise(r => child.on('close', r)); if (code !== 0) break;
+    } else if (t.runner === 'node') {
+      if (t.action) { const mod = await import(new URL('../' + t.action, import.meta.url)); if (typeof mod.default === 'function') { const r = await mod.default({ doc, task: t, env, flags }); if (r?.exitCode) code = r.exitCode; } }
+    } else if (t.runner === 'http') {
+      console.warn('[stub] http runner not implemented');
+    } else if (t.runner === 'forge' || t.runner === 'ai') {
+      console.warn(`[stub] runner "${t.runner}" not implemented in community build`);
+    }
+  }
+  const e = doc.evaluation; const stars = Number(flags['eval.stars'] ?? 0);
+  if (e?.feedbackEndpoint && e?.contract==='stars_1_5' && stars>=1 && stars<=5) {
+    try { const res = await postJSON(e.feedbackEndpoint, e.authToken, { runId: flags.runId || Date.now().toString(36), taskId: flags.taskId || doc.id, stars, notes: flags['eval.notes']||'', context: e.context||{}, ts: new Date().toISOString() }); console.log(`[eval] posted: ${res.status}`); } catch(err){ console.warn('[eval] failed:', err.message); }
+  }
+  return code;
+}

package/lib/serve.js

@@ -0,0 +1,6 @@
+import { spawn } from 'node:child_process';
+export async function serve(doc) {
+  const cmd = doc.devServer?.command; if (!cmd) throw new Error('devServer.command not defined');
+  const [exe, ...args] = cmd.split(' '); const child = spawn(exe, args, { stdio: 'inherit', env: process.env });
+  await new Promise((r)=> child.on('close', r));
+}

package/lib/validate.js

@@ -0,0 +1,11 @@
+import Ajv from 'ajv';
+import fs from 'node:fs';
+import { resolveJos } from './resolve.js';
+const schema = JSON.parse(fs.readFileSync(new URL('../schemas/jos.v0.3.1.schema.json', import.meta.url)));
+export function validate(file) {
+  const doc = resolveJos(file);
+  const ajv = new Ajv({ allErrors: true, strict: false });
+  const check = ajv.compile(schema);
+  const ok = check(doc);
+  return { ok, errors: check.errors || [], doc };
+}

package/package.json

@@ -1,36 +1,62 @@
 {
   "name": "@josfox/jos",
-  "version": "0.2.1",
-  "description": "JOSFOX CLI \u2014 exposes `jos` command with .jos export & kinds/hierarchy",
+  "version": "3.1.0",
+  "description": "JOSFOX CLI \u2014 .jos v3.1 community runtime (validate/run/serve/pack/publish/doc/test/lint)",
+  "license": "MIT",
+  "type": "module",
   "bin": {
     "jos": "bin/jos.js"
   },
-  "type": "commonjs",
+  "files": [
+    "bin",
+    "lib",
+    "schemas",
+    "examples",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
   "keywords": [
     "jos",
     "josfox",
-    "cli",
     ".jos",
     "spec",
-    "export"
+    "ai",
+    "agents",
+    "forge",
+    "pipeline",
+    "task",
+    "bundle",
+    "marketplace",
+    "prompt-engineering",
+    "evaluation",
+    "cache",
+    "lineage",
+    "devserver",
+    "cloud",
+    "embeddable"
   ],
-  "author": "JOSFOX",
-  "license": "MIT",
-  "homepage": "https://github.com/josfox/jos",
+  "homepage": "https://github.com/josfox-ai/jos-format-spec",
+  "bugs": {
+    "url": "https://github.com/josfox-ai/jos-format-spec/issues"
+  },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/josfox/jos.git"
-  },
-  "bugs": {
-    "url": "https://github.com/josfox/jos/issues"
+    "url": "git+https://github.com/josfox-ai/jos-format-spec.git"
   },
+  "author": "JOSFOX Team",
+  "maintainers": [
+    {
+      "name": "JOSFOX",
+      "email": "oss@josfox.mx"
+    }
+  ],
   "engines": {
-    "node": ">=16"
+    "node": ">=18.17"
   },
-  "files": [
-    "bin",
-    "lib",
-    "README.md",
-    "LICENSE"
-  ]
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "yargs": "^17.7.2"
+  }
 }

package/schemas/jos.v0.3.1.schema.json

@@ -0,0 +1,64 @@
+{
+  "$id": "https://josfox.ai/spec/jos.v0.3.1.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "required": [
+    "schema",
+    "id",
+    "name",
+    "version",
+    "kind"
+  ],
+  "properties": {
+    "schema": {
+      "const": "jos.v0.3.1"
+    },
+    "id": {
+      "type": "string"
+    },
+    "name": {
+      "type": "string"
+    },
+    "version": {
+      "type": "string"
+    },
+    "kind": {
+      "enum": [
+        "task",
+        "pipeline",
+        "bundle"
+      ]
+    },
+    "$extends": {
+      "type": "string"
+    },
+    "$imports": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "inputs": {
+      "type": "object"
+    },
+    "secrets": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "envMap": {
+      "type": "object"
+    },
+    "tasks": {
+      "type": "array"
+    },
+    "devServer": {
+      "type": "object"
+    },
+    "evaluation": {
+      "type": "object"
+    }
+  },
+  "additionalProperties": true
+}

package/lib/spec.js

@@ -1,25 +0,0 @@
-const DEFAULT_SPEC = {"version":"v2","kind":"Pack","name":"example-pack","description":"Example JOS Pack with prompts and an agent.","imports":[{"kind":"Prompt","ref":"./prompts/greet","as":"greet"},{"kind":"Prompt","ref":"./prompts/farewell","as":"bye"}],"prompts":{"greet":{"kind":"Prompt","id":"greet","template":"Hello, {{name}}!"},"farewell":{"kind":"Prompt","id":"farewell","template":"Bye, {{name}}."}},"agents":{"support":{"kind":"Agent","uses":["greet","farewell"],"vars":{"tone":"friendly"},"routes":[{"when":"start","do":"greet"},{"when":"end","do":"farewell"}]}},"meta":{"createdBy":"jos","kinds":["Prompt","Pack","Agent","App"],"hierarchy":{"Prompt":{"role":"leaf","canImport":[],"canContain":[]},"Pack":{"role":"library","canImport":["Prompt","Pack"],"canContain":["Prompt","Agent"]},"Agent":{"role":"runtime","canImport":["Prompt","Pack"],"canContain":[]},"App":{"role":"product","canImport":["Agent","Pack"],"canContain":["Agent"]}}}};
-function asConsole(spec = DEFAULT_SPEC) {
-  const lines = [];
-  const meta = spec.meta || {}
-  const kinds = meta.kinds || [];
-  const hierarchy = meta.hierarchy || {}
-  lines.push('JOS Spec');
-  lines.push(`version: ${spec.version}`);
-  lines.push(`kind: ${spec.kind}`);
-  lines.push('kinds:');
-  kinds.forEach(kind => lines.push(`  - ${kind}`));
-  lines.push('hierarchy:');
-  Object.keys(hierarchy).forEach(key => {
-    const h = hierarchy[key];
-    const imp = (h.canImport || []).join(',');
-    const cont = (h.canContain || []).join(',');
-    lines.push(`  ${key}: role=${h.role || ''}, canImport=${imp}, canContain=${cont}`);
-  });
-  const prompts = Object.keys(spec.prompts || {});
-  const agents = Object.keys(spec.agents || {});
-  lines.push('prompts:' + (prompts.length ? ' ' + prompts.join(', ') : ' (none)'));
-  lines.push('agents:' + (agents.length ? ' ' + agents.join(', ') : ' (none)'));
-  return lines.join('\n');
-}
-module.exports = { DEFAULT_SPEC, asConsole };