@evcraddock/slug-cli 0.6.0 → 0.6.1

package/README.md

@@ -25,7 +25,7 @@ Create a standalone site with:
 slug init ./my-site --name my-site --site-title "My Site"
 ```
 
-Run `slug init --help` for template options. In repository-local development, `slug init` copies `template/site` directly. Installed CLI releases download the matching versioned template asset from the Forgejo release unless `--template-url` or `--template-dir` is provided.
+Run `slug init --help` for template options. By default, `slug init` consumes the package-backed `@evcraddock/slug-template` default template. `--template-dir` and `--template-url` remain available for local or remote template testing, and `--template` reserves the selection path for future named or external template packages.
 
 ## Login and configuration
 
@@ -49,6 +49,8 @@ The CLI stores YAML config at `${XDG_CONFIG_HOME:-~/.config}/slug/config.yaml` b
 
 Use `slug --site <name> site config show` to read supported runtime site configuration through the Slugkit API. Use `slug --site <name> site config set <field> <value>` to update supported fields such as `name`, `url`, `tagline`, `description`, `homepage.intro`, and `homepage.body`.
 
+Use `slug --site <name> doctor` to check API compatibility and package metadata. Use `slug --site <name> upgrade` for advisory, non-destructive package update recommendations; it reports suggested dependency changes without rewriting site files.
+
 Use `slug --site <name> post list`, `slug --site <name> post show <slug>`, `slug --site <name> post create`, `slug --site <name> post edit <slug>`, `slug --site <name> post publish <slug>`, `slug --site <name> post unpublish <slug>`, and `slug --site <name> post delete <slug>` to manage posts through the Slugkit posts API.
 
 Use `slug tag list` to list tags and post usage counts through the Slugkit tags API.

package/dist/commands.js

@@ -4,6 +4,8 @@ import { tmpdir } from "node:os";
 import { dirname, basename, extname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { x as extractTarball } from "tar";
+import { SLUGKIT_API_MAJOR_VERSION, SLUGKIT_API_NAME, compareSlugkitApiVersions, normalizeApiBaseUrl, readSlugkitApiMajorVersion, } from "@evcraddock/slug-core";
+import { GENERATED_SITE_SLUGKIT_DEPENDENCIES, SLUGKIT_TEMPLATE_PACKAGE_NAME, getTemplateMetadata, getTemplateRoot, isTemplateEntryIncluded, } from "@evcraddock/slug-template";
 import { isValidSiteName, readConfig, removeConfigSite, setConfigSiteApiBaseUrl, setConfigSiteApiKey, toDisplayConfig, writeConfig, } from "./config.js";
 import { CliError, createInvalidUsageError, ExitCode } from "./errors.js";
 import { SlugHttpClient } from "./http.js";
@@ -15,8 +17,9 @@ Usage:
   slug [--config <file>] [--site <name>] --version
   slug [--config <file>] [--site <name>] version [--json]
   slug [--config <file>] --site <name> doctor [--json]
+  slug [--config <file>] --site <name> upgrade [--json]
   slug [--config <file>] --site <name> login [api-base-url]
-  slug [--config <file>] init <directory> --name <name> [--site-title <title>] [--template-url <url>] [--template-dir <dir>] [--json]
+  slug [--config <file>] init <directory> --name <name> [--site-title <title>] [--template <name>] [--template-url <url>] [--template-dir <dir>] [--json]
   slug [--config <file>] --site <name> post list [--type article|link|note] [--status draft|published|all] [--tag <slug>] [--json]
   slug [--config <file>] post show <slug> [--json]
   slug [--config <file>] post create --type article|link|note --slug <slug> --content <text> [--title <text>] [--url <url>] [--excerpt <text>] [--tag <slug>]... [--source-id <id>] [--credit-contact-id <id>]... [--json]
@@ -84,6 +87,8 @@ export async function runCommand(context) {
             return runVersionCommand(context, args.slice(1));
         case "doctor":
             return runDoctorCommand(context, args.slice(1));
+        case "upgrade":
+            return runUpgradeCommand(context, args.slice(1));
         case "login":
             return runLoginCommand(context, args.slice(1));
         case "init":
@@ -128,24 +133,25 @@ async function runVersionCommand(context, args) {
     }
     return { exitCode: ExitCode.Ok };
 }
-const SUPPORTED_API_MAJOR_VERSION = 1;
-const SITE_TEMPLATE_PACKAGE_NAME = "@slugkit/template-site";
-const SITE_TEMPLATE_RELEASE_BASE_URL = "https://forge.caradoc.com/erik/slugkit/releases/download";
+const SUPPORTED_API_MAJOR_VERSION = SLUGKIT_API_MAJOR_VERSION;
+const SITE_TEMPLATE_PACKAGE_NAME = getTemplateMetadata().templateSitePackageName;
+const DEFAULT_TEMPLATE_METADATA = getTemplateMetadata();
+const DEFAULT_TEMPLATE_NAME = DEFAULT_TEMPLATE_METADATA.name;
 const INIT_HELP_TEXT = `slug init - create a standalone Slugkit-compatible website
 
 Usage:
-  slug init <directory> --name <name> [--site-title <title>] [--template-url <url>] [--template-dir <dir>] [--json]
+  slug init <directory> --name <name> [--site-title <title>] [--template <name>] [--template-url <url>] [--template-dir <dir>] [--json]
 
 Options:
   --name <name>          npm package name for the generated site.
   --site-title <title>   Human-readable site title. Defaults to a title derived from --name.
+  --template <name>      Template name or package. Defaults to ${DEFAULT_TEMPLATE_NAME}.
   --template-url <url>   Download a template tarball from a custom URL.
   --template-dir <dir>   Copy a template from a local directory.
   --json                 Print command output as JSON.
   --help, -h             Show this help.
 
-By default, slug init uses the repository-local template/site directory when available.
-Installed CLI releases download the versioned template asset that matches the CLI version.`;
+By default, slug init uses ${SLUGKIT_TEMPLATE_PACKAGE_NAME}. Template packages are initialization sources only; generated sites do not depend on them at runtime.`;
 const SITE_INIT_NEXT_STEPS = [
     "Install dependencies",
     "Copy and edit .env",
@@ -155,14 +161,6 @@ const SITE_INIT_NEXT_STEPS = [
     "Configure ActivityPub domain and actor settings",
     "Configure slug and run slug doctor",
 ];
-const TEMPLATE_COPY_EXCLUDES = new Set([
-    ".env",
-    "node_modules",
-    "dist",
-    "build",
-    "data",
-    "coverage",
-]);
 async function runInitCommand(context, args) {
     if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
         context.writer.stdout(INIT_HELP_TEXT);
@@ -205,6 +203,7 @@ function parseInitArgs(args) {
     let directory;
     let name;
     let siteTitle;
+    let template;
     let templateUrl;
     let templateDir;
     let json = false;
@@ -224,6 +223,11 @@ function parseInitArgs(args) {
             index += 1;
             continue;
         }
+        if (arg === "--template") {
+            template = readRequiredInitOptionValue(args, index, "template");
+            index += 1;
+            continue;
+        }
         if (arg === "--template-url") {
             templateUrl = readRequiredInitOptionValue(args, index, "template-url");
             index += 1;
@@ -238,15 +242,18 @@ function parseInitArgs(args) {
             throw createInvalidUsageError(`Unsupported option: ${arg}`);
         }
         if (directory !== undefined || arg === undefined) {
-            throw createInvalidUsageError("Usage: slug init <directory> --name <name> [--site-title <title>] [--template-url <url>] [--template-dir <dir>] [--json]");
+            throw createInvalidUsageError("Usage: slug init <directory> --name <name> [--site-title <title>] [--template <name>] [--template-url <url>] [--template-dir <dir>] [--json]");
         }
         directory = arg;
     }
     if (directory === undefined || name === undefined) {
-        throw createInvalidUsageError("Usage: slug init <directory> --name <name> [--site-title <title>] [--template-url <url>] [--template-dir <dir>] [--json]");
+        throw createInvalidUsageError("Usage: slug init <directory> --name <name> [--site-title <title>] [--template <name>] [--template-url <url>] [--template-dir <dir>] [--json]");
     }
     const normalizedName = name.trim();
     validatePackageName(normalizedName);
+    if (template !== undefined && (templateUrl !== undefined || templateDir !== undefined)) {
+        throw createInvalidUsageError("Use --template, --template-url, or --template-dir, not more than one");
+    }
     if (templateUrl !== undefined && templateDir !== undefined) {
         throw createInvalidUsageError("Use only one of --template-url or --template-dir");
     }
@@ -255,6 +262,7 @@ function parseInitArgs(args) {
         name: normalizedName,
         siteTitle: siteTitle?.trim() || humanizePackageName(normalizedName),
         json,
+        template: template?.trim() || undefined,
         templateUrl: templateUrl?.trim() || undefined,
         templateDir: templateDir?.trim() || undefined,
     };
@@ -323,20 +331,15 @@ async function copyTemplateSite(source, destination, relativeDirectory = "") {
         }
     }
 }
-const GENERATED_SITE_TEST_EXCLUDES = new Set([
-    join("src", "__tests__", "dev-environment.test.ts"),
-    join("src", "federation", "__tests__", "follow.test.ts"),
-]);
-function shouldExcludeTemplateEntry(relativePath, name) {
-    return (GENERATED_SITE_TEST_EXCLUDES.has(relativePath) ||
-        TEMPLATE_COPY_EXCLUDES.has(name) ||
-        name.endsWith(".log") ||
-        name.endsWith(".tsbuildinfo"));
+function shouldExcludeTemplateEntry(relativePath, _name) {
+    return !isTemplateEntryIncluded(relativePath);
 }
 async function replaceGeneratedSitePlaceholders(directory, options) {
     await updateJsonFile(join(directory, "package.json"), (value) => ({
         ...value,
         name: options.name,
+        dependencies: replaceGeneratedSiteWorkspaceDependencies(value.dependencies),
+        devDependencies: replaceGeneratedSiteWorkspaceDependencies(value.devDependencies),
     }));
     await replaceTextFile(join(directory, "src", "config", "site.ts"), [
         ['name: "slugkit"', `name: ${JSON.stringify(options.siteTitle)}`],
@@ -365,6 +368,16 @@ async function replaceGeneratedSitePlaceholders(directory, options) {
         ],
     ]);
 }
+function replaceGeneratedSiteWorkspaceDependencies(value) {
+    if (!isRecord(value))
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([name, version]) => [
+        name,
+        version === "workspace:*" && GENERATED_SITE_SLUGKIT_DEPENDENCIES[name] !== undefined
+            ? GENERATED_SITE_SLUGKIT_DEPENDENCIES[name]
+            : version,
+    ]));
+}
 async function updateJsonFile(path, update) {
     const value = JSON.parse(await readFile(path, "utf8"));
     await writeFile(path, `${JSON.stringify(update(value), null, 2)}\n`, "utf8");
@@ -381,11 +394,24 @@ async function writeGeneratedSiteMarker(directory, options) {
         slugkitSite: true,
         name: options.name,
         siteTitle: options.siteTitle,
-        template: "slugkit/template-site",
+        template: `${SLUGKIT_TEMPLATE_PACKAGE_NAME}/${DEFAULT_TEMPLATE_NAME}`,
         generatedAt: new Date().toISOString(),
+        packageMetadata: createGeneratedSitePackageMetadata(DEFAULT_TEMPLATE_METADATA),
     };
     await writeFile(join(directory, ".slugkit-site.json"), `${JSON.stringify(marker, null, 2)}\n`, "utf8");
 }
+function createGeneratedSitePackageMetadata(metadata) {
+    return {
+        template: {
+            packageName: metadata.packageName,
+            name: metadata.name,
+            version: metadata.version,
+        },
+        packages: { ...metadata.includedSlugkitPackages },
+        advisoryOnly: true,
+        migrationNotesUrl: "https://slugkit.com/docs/package-updates",
+    };
+}
 async function resolveInitTemplateSource(context, options) {
     if (options.templateDir !== undefined) {
         const directory = resolve(options.templateDir);
@@ -395,20 +421,20 @@ async function resolveInitTemplateSource(context, options) {
     if (options.templateUrl !== undefined) {
         return downloadTemplateSite(context, options.templateUrl);
     }
+    if (options.template !== undefined) {
+        return resolveNamedTemplateSource(options.template);
+    }
     const localTemplateDirectory = findTemplateSiteDirectory(context.templateSiteDirectory);
     if (localTemplateDirectory !== undefined) {
         return { directory: localTemplateDirectory };
     }
-    return downloadTemplateSite(context, getDefaultTemplateAssetUrl(context));
-}
-function getDefaultTemplateAssetUrl(context) {
-    const version = context.packageVersion.trim().replace(/^v/, "");
-    const baseUrl = context.templateAssetBaseUrl ?? SITE_TEMPLATE_RELEASE_BASE_URL;
-    const assetName = getTemplateAssetName(version);
-    return `${baseUrl.replace(/\/$/u, "")}/v${encodeURIComponent(version)}/${encodeURIComponent(assetName)}`;
+    return { directory: getTemplateRoot() };
 }
-function getTemplateAssetName(version) {
-    return `slugkit-site-template-v${version}.tgz`;
+function resolveNamedTemplateSource(template) {
+    if (template === DEFAULT_TEMPLATE_NAME || template === SLUGKIT_TEMPLATE_PACKAGE_NAME) {
+        return { directory: getTemplateRoot() };
+    }
+    throw createInvalidUsageError(`Unsupported template: ${template}. This CLI currently includes ${DEFAULT_TEMPLATE_NAME}; future releases may resolve external template packages.`);
 }
 async function downloadTemplateSite(context, templateUrl) {
     let parsedUrl;
@@ -496,6 +522,7 @@ async function runDoctorCommand(context, args) {
     checks.push(createHealthCheck(health));
     const meta = await requestDoctorJson(context, apiBaseUrl, "/meta");
     checks.push(createMetaCheck(meta));
+    checks.push(createPackageMetadataCheck(meta));
     const openapi = await requestDoctorJson(context, apiBaseUrl, "/openapi.json");
     checks.push(createOpenApiCheck(openapi));
     if (config.apiKey === undefined || config.apiKey.trim() === "") {
@@ -595,10 +622,10 @@ function createMetaCheck(result) {
     if (!isMetaDocument(result.data)) {
         return { name: "meta", status: "fail", message: "Metadata response is invalid" };
     }
-    if (result.data.api.name !== "slugkit") {
+    if (result.data.api.name !== SLUGKIT_API_NAME) {
         return { name: "meta", status: "fail", message: "API name is not slugkit" };
     }
-    if (readMajorVersion(result.data.api.version) !== SUPPORTED_API_MAJOR_VERSION) {
+    if (readSlugkitApiMajorVersion(result.data.api.version) !== SUPPORTED_API_MAJOR_VERSION) {
         return {
             name: "meta",
             status: "fail",
@@ -607,6 +634,35 @@ function createMetaCheck(result) {
     }
     return { name: "meta", status: "pass", message: `API version ${result.data.api.version}` };
 }
+function createPackageMetadataCheck(result) {
+    if (!result.ok) {
+        return { name: "packages", status: "warn", message: "Package metadata is unavailable" };
+    }
+    if (!isMetaDocument(result.data) || result.data.packageMetadata === undefined) {
+        return {
+            name: "packages",
+            status: "warn",
+            message: "Package metadata is not exposed by this site",
+        };
+    }
+    const metadata = result.data.packageMetadata;
+    const stalePackages = findStaleSlugkitPackages(metadata.packages);
+    if (stalePackages.length > 0) {
+        return {
+            name: "packages",
+            status: "warn",
+            message: `Updates available: ${stalePackages
+                .map((entry) => `${entry.packageName} ${entry.currentVersion} → ${entry.recommendedVersion}`)
+                .join(", ")}`,
+        };
+    }
+    const packageCount = Object.keys(metadata.packages).length;
+    return {
+        name: "packages",
+        status: "pass",
+        message: `${packageCount} Slugkit package versions reported; upgrades are advisory`,
+    };
+}
 function createOpenApiCheck(result) {
     if (!result.ok) {
         return { name: "openapi", status: "fail", message: result.message };
@@ -645,13 +701,108 @@ function getDoctorExitCode(checks) {
     }
     return ExitCode.ApiError;
 }
+async function runUpgradeCommand(context, args) {
+    const json = readJsonFlag(args);
+    const siteResult = await readDoctorSiteConfig(context);
+    if (!siteResult.ok) {
+        const result = {
+            ok: false,
+            advisoryOnly: true,
+            message: siteResult.message,
+            recommendations: [],
+        };
+        return finishUpgrade(context, result, json, ExitCode.InvalidUsage);
+    }
+    const apiBaseUrl = normalizeUrl(siteResult.site.apiBaseUrl);
+    const meta = await requestDoctorJson(context, apiBaseUrl, "/meta");
+    if (!meta.ok) {
+        const result = {
+            ok: false,
+            advisoryOnly: true,
+            message: meta.message,
+            recommendations: [],
+        };
+        return finishUpgrade(context, result, json, getDoctorExitCode([{ name: "meta", status: "fail", message: meta.message }]));
+    }
+    if (!isMetaDocument(meta.data) || meta.data.packageMetadata === undefined) {
+        const result = {
+            ok: true,
+            advisoryOnly: true,
+            message: "Package metadata is unavailable; no files were changed.",
+            recommendations: [],
+        };
+        return finishUpgrade(context, result, json, ExitCode.Ok);
+    }
+    const metadata = meta.data.packageMetadata;
+    const recommendations = findStaleSlugkitPackages(metadata.packages);
+    const result = {
+        ok: true,
+        advisoryOnly: true,
+        message: recommendations.length === 0
+            ? "No Slugkit package updates are currently recommended. No files were changed."
+            : "Slugkit package updates are available. Review and apply them manually; no files were changed.",
+        recommendations,
+        migrationNotesUrl: metadata.migrationNotesUrl,
+    };
+    if (metadata.template !== undefined) {
+        result.template = `${metadata.template.packageName}/${metadata.template.name}@${metadata.template.version}`;
+    }
+    return finishUpgrade(context, result, json, ExitCode.Ok);
+}
+function finishUpgrade(context, result, json, exitCode) {
+    if (json) {
+        writeJson(context.writer, result);
+    }
+    else {
+        context.writer.stdout("Slug upgrade: advisory only");
+        context.writer.stdout(result.message);
+        if (result.template !== undefined) {
+            context.writer.stdout(`Template: ${result.template}`);
+        }
+        if (result.recommendations.length > 0) {
+            context.writer.stdout("Recommended package updates:");
+            for (const recommendation of result.recommendations) {
+                context.writer.stdout(`- ${recommendation.packageName}: ${recommendation.currentVersion} -> ${recommendation.recommendedVersion}`);
+            }
+        }
+        if (result.migrationNotesUrl !== undefined) {
+            context.writer.stdout(`Migration notes: ${result.migrationNotesUrl}`);
+        }
+    }
+    return { exitCode };
+}
 function isMetaDocument(value) {
     return (isRecord(value) &&
         isRecord(value.api) &&
         typeof value.api.name === "string" &&
         typeof value.api.version === "string" &&
         typeof value.api.baseUrl === "string" &&
-        typeof value.api.openapiUrl === "string");
+        typeof value.api.openapiUrl === "string" &&
+        (value.packageMetadata === undefined || isPackageMetadata(value.packageMetadata)));
+}
+function isPackageMetadata(value) {
+    return (isRecord(value) &&
+        isRecord(value.packages) &&
+        value.advisoryOnly === true &&
+        Object.values(value.packages).every((version) => typeof version === "string") &&
+        (value.template === undefined ||
+            (isRecord(value.template) &&
+                typeof value.template.packageName === "string" &&
+                typeof value.template.name === "string" &&
+                typeof value.template.version === "string")) &&
+        (value.migrationNotesUrl === undefined || typeof value.migrationNotesUrl === "string"));
+}
+function findStaleSlugkitPackages(packages) {
+    return Object.entries(GENERATED_SITE_SLUGKIT_DEPENDENCIES)
+        .map(([packageName, recommendedVersion]) => {
+        const currentVersion = packages[packageName];
+        if (currentVersion === undefined)
+            return undefined;
+        if (compareSlugkitApiVersions(currentVersion, recommendedVersion) >= 0)
+            return undefined;
+        return { packageName, currentVersion, recommendedVersion };
+    })
+        .filter((entry) => entry !== undefined);
 }
 function isOpenApiDocument(value) {
     return (isRecord(value) &&
@@ -663,10 +814,6 @@ function isOpenApiDocument(value) {
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function readMajorVersion(value) {
-    const major = Number.parseInt(value.split(".")[0] ?? "", 10);
-    return Number.isInteger(major) ? major : undefined;
-}
 function readApiErrorMessage(value) {
     if (!isRecord(value) || !isRecord(value.error) || typeof value.error.message !== "string") {
         return undefined;
@@ -2336,17 +2483,13 @@ export function createBrowserAuthUrl(apiBaseUrl) {
     return url.toString();
 }
 function normalizeUrl(value) {
-    validateUrl(value);
-    return value.replace(/\/+$/, "");
-}
-function validateUrl(value) {
     try {
-        const url = new URL(value);
-        if (url.protocol !== "http:" && url.protocol !== "https:") {
-            throw new Error("Unsupported protocol");
-        }
+        return normalizeApiBaseUrl(value);
     }
     catch {
         throw createInvalidUsageError("api-base-url must be a valid HTTP or HTTPS URL");
     }
 }
+function validateUrl(value) {
+    normalizeUrl(value);
+}

package/dist/http.d.ts

@@ -8,13 +8,6 @@ export interface HttpRequestOptions {
     path: string;
     body?: unknown;
 }
-export interface ApiErrorBody {
-    error?: {
-        code?: string;
-        message?: string;
-        operation?: string;
-    };
-}
 export declare class SlugHttpClient {
     private readonly apiBaseUrl;
     private readonly apiKey;

package/dist/http.js

@@ -1,10 +1,11 @@
+import { normalizeApiBaseUrl } from "@evcraddock/slug-core";
 import { CliError, ExitCode } from "./errors.js";
 export class SlugHttpClient {
     apiBaseUrl;
     apiKey;
     fetchImpl;
     constructor(options) {
-        this.apiBaseUrl = options.apiBaseUrl.replace(/\/$/, "");
+        this.apiBaseUrl = normalizeApiBaseUrl(options.apiBaseUrl);
         this.apiKey = options.apiKey;
         this.fetchImpl = options.fetchImpl ?? fetch;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evcraddock/slug-cli",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Command-line tool for Slugkit sites.",
   "private": false,
   "type": "module",
@@ -26,6 +26,8 @@
     "test:watch": "vitest --config ../vitest.config.ts src"
   },
   "dependencies": {
+    "@evcraddock/slug-core": "0.1.1",
+    "@evcraddock/slug-template": "0.1.1",
     "tar": "^7.5.16"
   }
 }