@foro-sh/foro 0.1.0 → 0.9.2

package/README.md

@@ -2,6 +2,31 @@
 
 This package is the TypeScript SDK for Foro.
 
+## `@foro-sh/foro/manifest-cases`
+
+The shared `foro.yaml` validation table, as typed data. Foro's Python
+`_manifest.py` is a port of [foro-sh/platform]'s
+`apps/api/src/services/manifest.ts`, so both implementations run this same
+table to guarantee they never disagree about what a valid manifest is — if
+they did, `foro check` would pass locally and the deploy would fail.
+
+```ts
+import { manifestCases } from '@foro-sh/foro/manifest-cases'
+
+for (const { name, yaml, expect } of manifestCases) {
+  // expect is { ok: true } or { ok: false, reason: ManifestRejectionReason }
+}
+```
+
+Each case asserts only accept/reject and the rejection reason; the resolved
+defaults an implementation produces stay covered by its own tests.
+
+The cases live in `packages/python/src/foro/manifest-cases.json` — the single
+source of truth — and are inlined into this package at build time. Add cases
+there, not here.
+
+[foro-sh/platform]: https://github.com/foro-sh/platform
+
 ## Development
 
 ```bash

package/dist/_generated-manifest-cases.d.ts

@@ -0,0 +1,166 @@
+export declare const rawManifestCases: readonly [{
+    readonly name: "minimal-valid";
+    readonly yaml: "name: my-server\nentrypoint: server.py\n";
+    readonly expect: {
+        readonly ok: true;
+    };
+}, {
+    readonly name: "nested-entrypoint";
+    readonly yaml: "name: my-server\nentrypoint: src/server.py\n";
+    readonly expect: {
+        readonly ok: true;
+    };
+}, {
+    readonly name: "all-fields";
+    readonly yaml: "name: my-server\nentrypoint: server.py\nbuild_path: app\npython_version: \"3.11\"\nport: 9000\ndependency_manager: poetry\n";
+    readonly expect: {
+        readonly ok: true;
+    };
+}, {
+    readonly name: "unquoted-python-version";
+    readonly yaml: "name: my-server\nentrypoint: server.py\npython_version: 3.12\n";
+    readonly expect: {
+        readonly ok: true;
+    };
+}, {
+    readonly name: "bad-name-uppercase";
+    readonly yaml: "name: My-Server\nentrypoint: server.py\n";
+    readonly expect: {
+        readonly ok: false;
+        readonly reason: "invalid_name";
+    };
+}, {
+    readonly name: "bad-name-too-short";
+    readonly yaml: "name: ab\nentrypoint: server.py\n";
+    readonly expect: {
+        readonly ok: false;
+        readonly reason: "invalid_name";
+    };
+}, {
+    readonly name: "missing-name";
+    readonly yaml: "entrypoint: server.py\n";
+    readonly expect: {
+        readonly ok: false;
+        readonly reason: "invalid_name";
+    };
+}, {
+    readonly name: "bad-entrypoint-traversal";
+    readonly yaml: "name: my-server\nentrypoint: ../server.py\n";
+    readonly expect: {
+        readonly ok: false;
+        readonly reason: "invalid_entrypoint";
+    };
+}, {
+    readonly name: "bad-entrypoint-absolute";
+    readonly yaml: "name: my-server\nentrypoint: /server.py\n";
+    readonly expect: {
+        readonly ok: false;
+        readonly reason: "invalid_entrypoint";
+    };
+}, {
+    readonly name: "bad-entrypoint-shell-metachar";
+    readonly yaml: "name: my-server\nentrypoint: \"server.py; rm -rf x\"\n";
+    readonly expect: {
+        readonly ok: false;
+        readonly reason: "invalid_entrypoint";
+    };
+}, {
+    readonly name: "missing-entrypoint";
+    readonly yaml: "name: my-server\n";
+    readonly expect: {
+        readonly ok: false;
+        readonly reason: "invalid_entrypoint";
+    };
+}, {
+    readonly name: "bad-build-path-traversal";
+    readonly yaml: "name: my-server\nentrypoint: server.py\nbuild_path: ../x\n";
+    readonly expect: {
+        readonly ok: false;
+        readonly reason: "invalid_build_path";
+    };
+}, {
+    readonly name: "bad-build-path-shell-metachar";
+    readonly yaml: "name: my-server\nentrypoint: server.py\nbuild_path: \". && whoami\"\n";
+    readonly expect: {
+        readonly ok: false;
+        readonly reason: "invalid_build_path";
+    };
+}, {
+    readonly name: "bad-build-path-space";
+    readonly yaml: "name: my-server\nentrypoint: server.py\nbuild_path: \"my services\"\n";
+    readonly expect: {
+        readonly ok: false;
+        readonly reason: "invalid_build_path";
+    };
+}, {
+    readonly name: "bad-build-path-newline";
+    readonly yaml: "name: my-server\nentrypoint: server.py\nbuild_path: \"app\\nUSER root\"\n";
+    readonly expect: {
+        readonly ok: false;
+        readonly reason: "invalid_build_path";
+    };
+}, {
+    readonly name: "bad-python-version";
+    readonly yaml: "name: my-server\nentrypoint: server.py\npython_version: \"3.9\"\n";
+    readonly expect: {
+        readonly ok: false;
+        readonly reason: "invalid_python_version";
+    };
+}, {
+    readonly name: "bad-port-too-low";
+    readonly yaml: "name: my-server\nentrypoint: server.py\nport: 80\n";
+    readonly expect: {
+        readonly ok: false;
+        readonly reason: "invalid_port";
+    };
+}, {
+    readonly name: "bad-port-too-high";
+    readonly yaml: "name: my-server\nentrypoint: server.py\nport: 70000\n";
+    readonly expect: {
+        readonly ok: false;
+        readonly reason: "invalid_port";
+    };
+}, {
+    readonly name: "bad-port-sidecar-reserved";
+    readonly yaml: "name: my-server\nentrypoint: server.py\nport: 8001\n";
+    readonly expect: {
+        readonly ok: false;
+        readonly reason: "invalid_port";
+    };
+}, {
+    readonly name: "bad-port-non-integer";
+    readonly yaml: "name: my-server\nentrypoint: server.py\nport: \"abc\"\n";
+    readonly expect: {
+        readonly ok: false;
+        readonly reason: "invalid_port";
+    };
+}, {
+    readonly name: "bad-dependency-manager";
+    readonly yaml: "name: my-server\nentrypoint: server.py\ndependency_manager: pipx\n";
+    readonly expect: {
+        readonly ok: false;
+        readonly reason: "invalid_dependency_manager";
+    };
+}, {
+    readonly name: "invalid-yaml";
+    readonly yaml: "name: [unclosed\n";
+    readonly expect: {
+        readonly ok: false;
+        readonly reason: "invalid_yaml";
+    };
+}, {
+    readonly name: "invalid-shape-scalar";
+    readonly yaml: "just a string\n";
+    readonly expect: {
+        readonly ok: false;
+        readonly reason: "invalid_shape";
+    };
+}, {
+    readonly name: "invalid-shape-list";
+    readonly yaml: "- one\n- two\n";
+    readonly expect: {
+        readonly ok: false;
+        readonly reason: "invalid_shape";
+    };
+}];
+//# sourceMappingURL=_generated-manifest-cases.d.ts.map

package/dist/_generated-manifest-cases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_generated-manifest-cases.d.ts","sourceRoot":"","sources":["../src/_generated-manifest-cases.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6LnB,CAAA"}

package/dist/_generated-manifest-cases.js

@@ -0,0 +1,192 @@
+// Generated by scripts/generate-manifest-cases.mjs from the Python package's
+// manifest-cases.json. Do not edit - edit the JSON and rebuild.
+export const rawManifestCases = [
+    {
+        "name": "minimal-valid",
+        "yaml": "name: my-server\nentrypoint: server.py\n",
+        "expect": {
+            "ok": true
+        }
+    },
+    {
+        "name": "nested-entrypoint",
+        "yaml": "name: my-server\nentrypoint: src/server.py\n",
+        "expect": {
+            "ok": true
+        }
+    },
+    {
+        "name": "all-fields",
+        "yaml": "name: my-server\nentrypoint: server.py\nbuild_path: app\npython_version: \"3.11\"\nport: 9000\ndependency_manager: poetry\n",
+        "expect": {
+            "ok": true
+        }
+    },
+    {
+        "name": "unquoted-python-version",
+        "yaml": "name: my-server\nentrypoint: server.py\npython_version: 3.12\n",
+        "expect": {
+            "ok": true
+        }
+    },
+    {
+        "name": "bad-name-uppercase",
+        "yaml": "name: My-Server\nentrypoint: server.py\n",
+        "expect": {
+            "ok": false,
+            "reason": "invalid_name"
+        }
+    },
+    {
+        "name": "bad-name-too-short",
+        "yaml": "name: ab\nentrypoint: server.py\n",
+        "expect": {
+            "ok": false,
+            "reason": "invalid_name"
+        }
+    },
+    {
+        "name": "missing-name",
+        "yaml": "entrypoint: server.py\n",
+        "expect": {
+            "ok": false,
+            "reason": "invalid_name"
+        }
+    },
+    {
+        "name": "bad-entrypoint-traversal",
+        "yaml": "name: my-server\nentrypoint: ../server.py\n",
+        "expect": {
+            "ok": false,
+            "reason": "invalid_entrypoint"
+        }
+    },
+    {
+        "name": "bad-entrypoint-absolute",
+        "yaml": "name: my-server\nentrypoint: /server.py\n",
+        "expect": {
+            "ok": false,
+            "reason": "invalid_entrypoint"
+        }
+    },
+    {
+        "name": "bad-entrypoint-shell-metachar",
+        "yaml": "name: my-server\nentrypoint: \"server.py; rm -rf x\"\n",
+        "expect": {
+            "ok": false,
+            "reason": "invalid_entrypoint"
+        }
+    },
+    {
+        "name": "missing-entrypoint",
+        "yaml": "name: my-server\n",
+        "expect": {
+            "ok": false,
+            "reason": "invalid_entrypoint"
+        }
+    },
+    {
+        "name": "bad-build-path-traversal",
+        "yaml": "name: my-server\nentrypoint: server.py\nbuild_path: ../x\n",
+        "expect": {
+            "ok": false,
+            "reason": "invalid_build_path"
+        }
+    },
+    {
+        "name": "bad-build-path-shell-metachar",
+        "yaml": "name: my-server\nentrypoint: server.py\nbuild_path: \". && whoami\"\n",
+        "expect": {
+            "ok": false,
+            "reason": "invalid_build_path"
+        }
+    },
+    {
+        "name": "bad-build-path-space",
+        "yaml": "name: my-server\nentrypoint: server.py\nbuild_path: \"my services\"\n",
+        "expect": {
+            "ok": false,
+            "reason": "invalid_build_path"
+        }
+    },
+    {
+        "name": "bad-build-path-newline",
+        "yaml": "name: my-server\nentrypoint: server.py\nbuild_path: \"app\\nUSER root\"\n",
+        "expect": {
+            "ok": false,
+            "reason": "invalid_build_path"
+        }
+    },
+    {
+        "name": "bad-python-version",
+        "yaml": "name: my-server\nentrypoint: server.py\npython_version: \"3.9\"\n",
+        "expect": {
+            "ok": false,
+            "reason": "invalid_python_version"
+        }
+    },
+    {
+        "name": "bad-port-too-low",
+        "yaml": "name: my-server\nentrypoint: server.py\nport: 80\n",
+        "expect": {
+            "ok": false,
+            "reason": "invalid_port"
+        }
+    },
+    {
+        "name": "bad-port-too-high",
+        "yaml": "name: my-server\nentrypoint: server.py\nport: 70000\n",
+        "expect": {
+            "ok": false,
+            "reason": "invalid_port"
+        }
+    },
+    {
+        "name": "bad-port-sidecar-reserved",
+        "yaml": "name: my-server\nentrypoint: server.py\nport: 8001\n",
+        "expect": {
+            "ok": false,
+            "reason": "invalid_port"
+        }
+    },
+    {
+        "name": "bad-port-non-integer",
+        "yaml": "name: my-server\nentrypoint: server.py\nport: \"abc\"\n",
+        "expect": {
+            "ok": false,
+            "reason": "invalid_port"
+        }
+    },
+    {
+        "name": "bad-dependency-manager",
+        "yaml": "name: my-server\nentrypoint: server.py\ndependency_manager: pipx\n",
+        "expect": {
+            "ok": false,
+            "reason": "invalid_dependency_manager"
+        }
+    },
+    {
+        "name": "invalid-yaml",
+        "yaml": "name: [unclosed\n",
+        "expect": {
+            "ok": false,
+            "reason": "invalid_yaml"
+        }
+    },
+    {
+        "name": "invalid-shape-scalar",
+        "yaml": "just a string\n",
+        "expect": {
+            "ok": false,
+            "reason": "invalid_shape"
+        }
+    },
+    {
+        "name": "invalid-shape-list",
+        "yaml": "- one\n- two\n",
+        "expect": {
+            "ok": false,
+            "reason": "invalid_shape"
+        }
+    }
+];

package/dist/manifest-cases.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The shared `foro.yaml` validation table.
+ *
+ * foro's `_manifest.py` is a port of foro-sh/platform's
+ * `apps/api/src/services/manifest.ts`, and the two can never be allowed to
+ * silently disagree about what a valid manifest is - if they do, `foro check`
+ * passes locally and the deploy fails, which is the exact gap this SDK exists
+ * to close. Both sides therefore run the same table: the Python package
+ * through `tests/test_manifest_cases.py`, the platform by importing
+ * `manifestCases` from here (foro-sh/foro#5).
+ *
+ * The cases assert only accept/reject and the rejection reason - the resolved
+ * defaults each implementation produces stay covered by its own tests.
+ */
+/** Mirrors `ManifestRejectionReason` in foro-sh/platform's `@foro/types`.
+ *  Kept in sync deliberately: it is what makes a reason added on one side a
+ *  compile error on the other. */
+export type ManifestRejectionReason = 'missing_manifest' | 'unsupported_language' | 'invalid_yaml' | 'invalid_shape' | 'invalid_name' | 'invalid_entrypoint' | 'invalid_build_path' | 'invalid_python_version' | 'invalid_port' | 'invalid_dependency_manager' | 'unsupported_project';
+export interface ManifestCase {
+    /** Stable identifier, unique across the table - use it as the test name. */
+    readonly name: string;
+    /** Verbatim `foro.yaml` contents to validate. */
+    readonly yaml: string;
+    readonly expect: {
+        readonly ok: true;
+    } | {
+        readonly ok: false;
+        readonly reason: ManifestRejectionReason;
+    };
+}
+export declare const manifestCases: readonly ManifestCase[];
+//# sourceMappingURL=manifest-cases.d.ts.map

package/dist/manifest-cases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-cases.d.ts","sourceRoot":"","sources":["../src/manifest-cases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH;;kCAEkC;AAClC,MAAM,MAAM,uBAAuB,GAC/B,kBAAkB,GAClB,sBAAsB,GACtB,cAAc,GACd,eAAe,GACf,cAAc,GACd,oBAAoB,GACpB,oBAAoB,GACpB,wBAAwB,GACxB,cAAc,GACd,4BAA4B,GAC5B,qBAAqB,CAAA;AAEzB,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EACX;QAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;KAAE,GACrB;QAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAA;KAAE,CAAA;CACrE;AAED,eAAO,MAAM,aAAa,EAAE,SAAS,YAAY,EAAqB,CAAA"}

package/dist/manifest-cases.js

@@ -0,0 +1,16 @@
+/**
+ * The shared `foro.yaml` validation table.
+ *
+ * foro's `_manifest.py` is a port of foro-sh/platform's
+ * `apps/api/src/services/manifest.ts`, and the two can never be allowed to
+ * silently disagree about what a valid manifest is - if they do, `foro check`
+ * passes locally and the deploy fails, which is the exact gap this SDK exists
+ * to close. Both sides therefore run the same table: the Python package
+ * through `tests/test_manifest_cases.py`, the platform by importing
+ * `manifestCases` from here (foro-sh/foro#5).
+ *
+ * The cases assert only accept/reject and the rejection reason - the resolved
+ * defaults each implementation produces stay covered by its own tests.
+ */
+import { rawManifestCases } from './_generated-manifest-cases.js';
+export const manifestCases = rawManifestCases;

package/dist/manifest-cases.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=manifest-cases.test.d.ts.map

package/dist/manifest-cases.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-cases.test.d.ts","sourceRoot":"","sources":["../src/manifest-cases.test.ts"],"names":[],"mappings":""}

package/dist/manifest-cases.test.js

@@ -0,0 +1,23 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { manifestCases } from './manifest-cases.js';
+// Sanity checks on the shared table itself - the generator
+// (scripts/generate-manifest-cases.mjs) already enforces these invariants at
+// build time, but that only runs when someone builds this package locally.
+// A real `.test.ts` here means CI catches a malformed table on every push,
+// not just when a maintainer happens to run `npm run build`.
+test('manifestCases is non-empty', () => {
+    assert.ok(manifestCases.length > 0);
+});
+test('every case name is unique', () => {
+    const names = manifestCases.map((c) => c.name);
+    assert.equal(new Set(names).size, names.length);
+});
+test('every case has non-empty yaml and a well-formed expect', () => {
+    for (const testCase of manifestCases) {
+        assert.ok(testCase.yaml.length > 0, `${testCase.name}: empty yaml`);
+        if (testCase.expect.ok)
+            continue;
+        assert.ok(typeof testCase.expect.reason === 'string' && testCase.expect.reason.length > 0, `${testCase.name}: missing rejection reason`);
+    }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@foro-sh/foro",
-    "version": "0.1.0",
+    "version": "0.9.2",
     "description": "TypeScript SDK for Foro",
     "type": "module",
     "main": "dist/index.js",
@@ -10,13 +10,18 @@
             "types": "./dist/index.d.ts",
             "import": "./dist/index.js",
             "default": "./dist/index.js"
+        },
+        "./manifest-cases": {
+            "types": "./dist/manifest-cases.d.ts",
+            "import": "./dist/manifest-cases.js",
+            "default": "./dist/manifest-cases.js"
         }
     },
     "files": [
         "dist"
     ],
     "scripts": {
-        "build": "tsc -p tsconfig.json",
+        "build": "node scripts/generate-manifest-cases.mjs && tsc -p tsconfig.json",
         "prepublishOnly": "npm run build",
         "test": "node --test dist/**/*.test.js"
     },
@@ -42,6 +47,7 @@
         "node": ">=18"
     },
     "devDependencies": {
+        "@types/node": "^20.11.0",
         "typescript": "^5.6.3"
     }
-}
+}