tessello 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 craftskillz
+
+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

@@ -1,3 +1,11 @@
-# Temporary Holding Version
+# tessello
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Tessello command-line tool.
+
+```sh
+npx tessello validate my-module          # a Module folder
+npx tessello validate my-module.zip      # or its .zip
+npx tessello validate my-module --json   # the report as JSON
+```
+
+It checks the Module against the Tessello [Convention](https://github.com/craftskillz/tessello/blob/main/convention/CONVENTION.md) and exits with 1 when the Module is not installable, 0 otherwise. Every error and warning names the file and says what to change: fix them until there is no error left, then zip the *contents* of the folder (not the folder itself).

package/cli.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { formatReport, validatePath } from "./validate-command.js";
+const USAGE = `Usage: tessello <command>
+
+Commands:
+  validate <path> [--json]   Check a Module folder or .zip against the Tessello Convention.
+                             Exits with 1 if the Module is not installable.`;
+/** Runs the CLI and returns the process exit code: 0 success, 1 invalid Module, 2 usage error. */
+export async function run(args, output) {
+    const [command, ...rest] = args;
+    if (command === "validate") {
+        const json = rest.includes("--json");
+        const paths = rest.filter((arg) => arg !== "--json");
+        if (paths.length !== 1) {
+            output.err(USAGE);
+            return 2;
+        }
+        const target = paths[0];
+        let report;
+        try {
+            report = await validatePath(target);
+        }
+        catch (e) {
+            output.err(`Cannot read "${target}": ${e.message}`);
+            return 2;
+        }
+        output.out(json ? JSON.stringify(report, null, 2) : formatReport(target, report));
+        return report.valid ? 0 : 1;
+    }
+    if (command === undefined || command === "help" || command === "--help" || command === "-h") {
+        output.out(USAGE);
+        return command === undefined ? 2 : 0;
+    }
+    output.err(`Unknown command "${command}".\n\n${USAGE}`);
+    return 2;
+}
+// npm runs the CLI through a symbolic link (node_modules/.bin/tessello), hence the real path.
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    process.exitCode = await run(process.argv.slice(2), {
+        out: (text) => console.log(text),
+        err: (text) => console.error(text),
+    });
+}

package/package.json

@@ -1,6 +1,22 @@
 {
   "name": "tessello",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Tessello command-line tool.",
+  "license": "MIT",
+  "type": "module",
+  "dependencies": {
+    "@tessello/convention": "0.1.0"
+  },
+  "bin": {
+    "tessello": "./cli.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/craftskillz/tessello.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/craftskillz/tessello#readme",
+  "engines": {
+    "node": ">=22.12"
+  }
+}

package/validate-command.js

@@ -0,0 +1,45 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import { validatePackage, validateZip } from "@tessello/convention";
+// Files a Creator's folder may contain that are never part of a package.
+const IGNORED_NAMES = new Set([".DS_Store", ".git"]);
+/** Validates a Module folder or .zip archive on disk. */
+export async function validatePath(path) {
+    const info = await stat(path);
+    if (info.isDirectory())
+        return validatePackage(await readFolder(path));
+    return validateZip(new Uint8Array(await readFile(path)));
+}
+async function readFolder(root) {
+    const files = new Map();
+    const entries = await readdir(root, { recursive: true, withFileTypes: true });
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        const absolute = join(entry.parentPath, entry.name);
+        const path = relative(root, absolute).split(sep).join("/");
+        if (path.split("/").some((part) => IGNORED_NAMES.has(part)))
+            continue;
+        files.set(path, new Uint8Array(await readFile(absolute)));
+    }
+    return files;
+}
+/** Human-readable report, meant to be read by Creators and by LLMs fixing their Module. */
+export function formatReport(target, report) {
+    const lines = [];
+    const identity = report.manifest ? ` (${report.manifest.id} ${report.manifest.version})` : "";
+    lines.push(`Validating ${target}${identity}`);
+    const errors = report.issues.filter((issue) => issue.severity === "error");
+    const warnings = report.issues.filter((issue) => issue.severity === "warning");
+    for (const issue of [...errors, ...warnings])
+        lines.push(formatIssue(issue));
+    const count = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+    lines.push(report.valid
+        ? `✓ ${count(warnings.length, "warning")}: this Module is installable.`
+        : `${count(errors.length, "error")}, ${count(warnings.length, "warning")}: this Module is not installable.`);
+    return lines.join("\n");
+}
+function formatIssue(issue) {
+    const mark = issue.severity === "error" ? "✗" : "⚠";
+    return `${mark} ${issue.message} [${issue.code}]`;
+}