@hutusi/amytis 1.9.0 → 1.11.0

package/docs/DIGITAL_GARDEN.md

@@ -26,7 +26,7 @@ You can link between any content (Posts, Notes, Flows) using double-bracket synt
 - **Cross-Type Linking:**
   - If a slug matches a Note, it links to `/notes/[slug]`
   - If it matches a Post, it links to `/posts/[slug]`
-  - If it matches a Flow, it links to `/flows/[slug]`
+  - If it matches a Flow date slug, it links to `/flows/YYYY/MM/DD`
 
 ### 3. Backlinks
 At the bottom of every Note, Amytis automatically generates a "Linked References" section. This lists every other page that links *to* the current note, along with a context snippet showing how it was referenced.
@@ -46,27 +46,29 @@ Flows are a stream-style collection of daily notes, micro-blogging, or imported
 
 ## How to Use
 
-1. **Create a Note**: Run `bun run new-note "My Concept"` (or `bun run new "My Concept" --note`).
+1. **Create a Note**: Run `bun run new-note "My Concept"`.
 2. **Create a Flow**: Run `bun run new-flow`.
 3. **Link to it**: In a blog post, note, or flow, type `[[my-concept]]` or `[[2026-02-27]]`.
 4. **Explore**: Visit `/notes` or `/flows` to see your collection, or `/graph` to see the connections.
 
 ## Configuration
 
-In `site.config.ts`, you can configure the graph visualization:
+Flows are controlled by `site.config.ts`, while notes and the graph are always routed when corresponding content exists:
 
 ```typescript
 export const siteConfig = {
   // ...
   features: {
-    graph: {
+    flow: {
       enabled: true,
-      name: { en: "Graph", zh: "知识图谱" },
+      name: { en: "Flow", zh: "随笔" },
     },
-    notes: {
-      enabled: true,
-      name: { en: "Notes", zh: "笔记" },
-    }
   }
 };
 ```
+
+Related settings that shape the digital-garden experience live alongside that flag:
+
+- `flows.recentCount`: controls how many flow entries appear on the homepage.
+- `pagination.flows` and `pagination.notes`: control listing page sizes.
+- `homepage.sections`: lets you enable, disable, or reorder homepage sections such as recent flows.

package/docs/deployment.md

@@ -268,29 +268,46 @@ sudo certbot renew --dry-run
 
 ### Step 4: Automate Deployment (Optional)
 
-Create a deploy script on your local machine at `scripts/deploy.sh`:
+Amytis includes a built-in deploy command for Linux servers running nginx.
+
+#### Using `bun run deploy`
+
+First install `sshpass` on your local machine:
 
 ```bash
-#!/bin/bash
-set -e
+# macOS
+brew install hudochenkov/sshpass/sshpass
+
+# Linux
+apt install sshpass
+```
 
-SERVER="user@server"
-REMOTE_DIR="/var/www/amytis"
+Configure your server in `.env.local` (gitignored):
 
-echo "Building..."
-bun run build
+```env
+DEPLOY_HOST=192.168.1.1
+DEPLOY_USER=root
+DEPLOY_PASSWORD=yourpassword
+DEPLOY_PATH=/var/www/amytis
+```
 
-echo "Deploying to $SERVER..."
-rsync -avz --delete out/ "$SERVER:$REMOTE_DIR/"
+Then deploy with a single command:
 
-echo "Done! Site deployed."
+```bash
+bun run build
+bun run deploy
 ```
 
+You can also pass values as flags to override `.env.local`:
+
 ```bash
-chmod +x scripts/deploy.sh
-./scripts/deploy.sh
+bun run deploy --host 1.2.3.4 --user root --password mypass --path /var/www/amytis
 ```
 
+The script builds the `out/` directory, uploads it via rsync, and automatically reloads nginx.
+
+#### Using CI/CD
+
 Or use a CI/CD pipeline — add a job in your GitHub Actions workflow:
 
 ```yaml
@@ -323,5 +340,6 @@ Or use a CI/CD pipeline — add a job in your GitHub Actions workflow:
 |---|---|---|
 | Build | `bun run build` | Output in `out/` |
 | GitHub Pages | Push to `main` | With GitHub Actions workflow |
-| Linux (upload) | `rsync -avz --delete out/ user@server:/var/www/amytis/` | After local build |
+| Linux (one command) | `bun run deploy` | Requires `.env.local` with server config |
+| Linux (manual upload) | `rsync -avz --delete out/ user@server:/var/www/amytis/` | After local build |
 | Linux (on server) | `bun install && bun run build` | Clone repo on server |

package/eslint.config.mjs

@@ -14,6 +14,8 @@ const eslintConfig = defineConfig([
     "next-env.d.ts",
     // Generated at build time — not authored code
     "public/pagefind/**",
+    // Package compiled output — not authored code
+    "packages/*/dist/**",
   ]),
 ]);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hutusi/amytis",
-  "version": "1.9.0",
+  "version": "1.11.0",
   "description": "A high-performance digital garden and blog engine with Next.js 16 and Tailwind CSS v4",
   "repository": {
     "type": "git",
@@ -30,10 +30,11 @@
     "import-book": "bun scripts/import-book.ts",
     "sync-book": "bun scripts/sync-book-chapters.ts",
     "series-draft": "bun scripts/series-draft.ts",
+    "deploy": "bun scripts/deploy.ts",
     "start": "next start",
     "lint": "eslint",
-    "test": "bun test src tests/unit tests/tooling && bun run test:int",
-    "test:unit": "bun test src tests/unit",
+    "test": "bun test src tests/unit tests/tooling packages/create-amytis/src && bun run test:int",
+    "test:unit": "bun test src tests/unit packages/create-amytis/src",
     "test:int": "bun test tests/integration",
     "test:e2e": "bun test tests/e2e"
   },
@@ -44,6 +45,7 @@
     "github-slugger": "^2.0.0",
     "gray-matter": "^4.0.3",
     "image-size": "^2.0.2",
+    "katex": "^0.16.33",
     "mermaid": "^11.12.3",
     "next": "16.1.6",
     "next-image-export-optimizer": "^1.20.1",
@@ -56,8 +58,12 @@
     "rehype-katex": "^7.0.1",
     "rehype-raw": "^7.0.0",
     "rehype-slug": "^6.0.0",
+    "rehype-stringify": "^10.0.1",
     "remark-gfm": "^4.0.1",
     "remark-math": "^6.0.0",
+    "remark-parse": "^11.0.0",
+    "remark-rehype": "^11.1.2",
+    "unified": "^11.0.5",
     "unist-util-visit": "^5.1.0",
     "zod": "^4.3.6"
   },
@@ -65,7 +71,9 @@
     "@tailwindcss/postcss": "^4.1.18",
     "@types/bun": "^1.3.9",
     "@types/d3": "^7.4.3",
+    "@types/hast": "^3.0.4",
     "@types/image-size": "^0.8.0",
+    "@types/mdast": "^4.0.4",
     "@types/node": "^24.10.13",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
@@ -85,5 +93,6 @@
   "trustedDependencies": [
     "sharp",
     "unrs-resolver"
-  ]
+  ],
+  "workspaces": ["packages/*"]
 }

package/packages/create-amytis/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "create-amytis",
+  "version": "0.1.0",
+  "description": "Create a new Amytis digital garden",
+  "license": "MIT",
+  "bin": { "create-amytis": "./dist/index.js" },
+  "scripts": {
+    "build": "bun build src/index.ts --outfile dist/index.js --target node --sourcemap=none",
+    "dev": "bun src/index.ts",
+    "test": "bun test src"
+  },
+  "files": ["dist"]
+}

package/packages/create-amytis/src/index.test.ts

@@ -0,0 +1,187 @@
+import { describe, test, expect, afterAll } from "bun:test";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { patchSiteConfig, patchPackageJson } from "./index";
+
+// Minimal site.config.ts that mirrors the real file's patchable fields.
+// Inner backticks and `${` are escaped so they appear literally in the string.
+const SAMPLE_CONFIG = `\
+const siteConfig = {
+  title: { en: "Amytis", zh: "Amytis" },
+  description: { en: "Amytis — an elegant open-source framework for building your personal digital garden.", zh: "Amytis — 优雅的开源数字花园框架。" },
+  footerText: { en: \`© \${new Date().getFullYear()} Amytis. All rights reserved.\`, zh: \`© \${new Date().getFullYear()} Amytis. 保留所有权利。\` },
+  nav: [],
+};
+export default siteConfig;
+`;
+
+const SAMPLE_PKG = JSON.stringify(
+  {
+    name: "@hutusi/amytis",
+    version: "1.11.0",
+    private: false,
+    repository: { type: "git", url: "git+https://github.com/hutusi/amytis.git" },
+    bugs: { url: "https://github.com/hutusi/amytis/issues" },
+    homepage: "https://github.com/hutusi/amytis#readme",
+    dependencies: { next: "16.1.6" },
+  },
+  null,
+  2
+) + "\n";
+
+function makeTmpDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "create-amytis-test-"));
+}
+
+// ---------------------------------------------------------------------------
+// patchSiteConfig
+// ---------------------------------------------------------------------------
+
+describe("patchSiteConfig", () => {
+  const tmpDirs: string[] = [];
+
+  afterAll(() => {
+    for (const dir of tmpDirs) {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  function setup(): string {
+    const dir = makeTmpDir();
+    tmpDirs.push(dir);
+    fs.writeFileSync(path.join(dir, "site.config.ts"), SAMPLE_CONFIG);
+    return dir;
+  }
+
+  test("replaces title in both en and zh locales", () => {
+    const dir = setup();
+    patchSiteConfig(dir, "My Awesome Blog", "Some description");
+    const result = fs.readFileSync(path.join(dir, "site.config.ts"), "utf8");
+    expect(result).toContain(`title: { en: "My Awesome Blog", zh: "My Awesome Blog" }`);
+    expect(result).not.toContain(`en: "Amytis"`);
+  });
+
+  test("replaces description in both en and zh locales", () => {
+    const dir = setup();
+    patchSiteConfig(dir, "My Blog", "Notes from the garden");
+    const result = fs.readFileSync(path.join(dir, "site.config.ts"), "utf8");
+    expect(result).toContain(
+      `description: { en: "Notes from the garden", zh: "Notes from the garden" }`
+    );
+    expect(result).not.toContain("elegant open-source framework");
+  });
+
+  test("replaces footerText with new title", () => {
+    const dir = setup();
+    patchSiteConfig(dir, "GardenSite", "My description");
+    const result = fs.readFileSync(path.join(dir, "site.config.ts"), "utf8");
+    expect(result).toContain("GardenSite. All rights reserved.");
+    expect(result).toContain("GardenSite. 保留所有权利。");
+    expect(result).not.toContain("Amytis. All rights reserved.");
+  });
+
+  test("handles title with special characters (quotes, apostrophes)", () => {
+    const dir = setup();
+    patchSiteConfig(dir, `Ada's "Blog"`, "A description");
+    const result = fs.readFileSync(path.join(dir, "site.config.ts"), "utf8");
+    // JSON.stringify will escape the quotes safely
+    expect(result).toContain(`"Ada's \\"Blog\\""`);
+  });
+
+  test("preserves unrelated config fields", () => {
+    const dir = setup();
+    patchSiteConfig(dir, "My Blog", "My description");
+    const result = fs.readFileSync(path.join(dir, "site.config.ts"), "utf8");
+    expect(result).toContain("nav: []");
+    expect(result).toContain("export default siteConfig");
+  });
+
+  test("does not throw when site.config.ts is missing", () => {
+    const dir = makeTmpDir();
+    tmpDirs.push(dir);
+    // file intentionally absent
+    expect(() => patchSiteConfig(dir, "Title", "Desc")).not.toThrow();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// patchPackageJson
+// ---------------------------------------------------------------------------
+
+describe("patchPackageJson", () => {
+  const tmpDirs: string[] = [];
+
+  afterAll(() => {
+    for (const dir of tmpDirs) {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  function setup(): string {
+    const dir = makeTmpDir();
+    tmpDirs.push(dir);
+    fs.writeFileSync(path.join(dir, "package.json"), SAMPLE_PKG);
+    return dir;
+  }
+
+  function readPkg(dir: string): Record<string, unknown> {
+    return JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8")) as Record<
+      string,
+      unknown
+    >;
+  }
+
+  test("sets name to project name", () => {
+    const dir = setup();
+    patchPackageJson(dir, "my-garden");
+    expect(readPkg(dir).name).toBe("my-garden");
+  });
+
+  test("sets private to true", () => {
+    const dir = setup();
+    patchPackageJson(dir, "my-garden");
+    expect(readPkg(dir).private).toBe(true);
+  });
+
+  test("removes repository field", () => {
+    const dir = setup();
+    patchPackageJson(dir, "my-garden");
+    expect(readPkg(dir).repository).toBeUndefined();
+  });
+
+  test("removes bugs field", () => {
+    const dir = setup();
+    patchPackageJson(dir, "my-garden");
+    expect(readPkg(dir).bugs).toBeUndefined();
+  });
+
+  test("removes homepage field", () => {
+    const dir = setup();
+    patchPackageJson(dir, "my-garden");
+    expect(readPkg(dir).homepage).toBeUndefined();
+  });
+
+  test("preserves version and dependencies", () => {
+    const dir = setup();
+    patchPackageJson(dir, "my-garden");
+    const pkg = readPkg(dir);
+    expect(pkg.version).toBe("1.11.0");
+    expect(pkg.dependencies).toEqual({ next: "16.1.6" });
+  });
+
+  test("output is valid JSON with trailing newline", () => {
+    const dir = setup();
+    patchPackageJson(dir, "my-garden");
+    const raw = fs.readFileSync(path.join(dir, "package.json"), "utf8");
+    expect(() => JSON.parse(raw)).not.toThrow();
+    expect(raw.endsWith("\n")).toBe(true);
+  });
+
+  test("does not throw when package.json is missing", () => {
+    const dir = makeTmpDir();
+    tmpDirs.push(dir);
+    // file intentionally absent
+    expect(() => patchPackageJson(dir, "my-garden")).not.toThrow();
+  });
+});

package/packages/create-amytis/src/index.ts

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+
+import * as fs from "fs";
+import * as path from "path";
+import * as https from "https";
+import * as readline from "readline";
+import { execSync } from "child_process";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function prompt(question: string, defaultVal: string = ""): Promise<string> {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  const display = defaultVal ? `${question} (${defaultVal}): ` : `${question}: `;
+  return new Promise((resolve) => {
+    rl.question(display, (answer) => {
+      rl.close();
+      resolve(answer.trim() || defaultVal);
+    });
+  });
+}
+
+function fetchJson(url: string): Promise<Record<string, unknown>> {
+  return new Promise((resolve, reject) => {
+    https
+      .get(url, { headers: { "User-Agent": "create-amytis-cli" } }, (res) => {
+        if (res.statusCode === 301 || res.statusCode === 302) {
+          fetchJson(res.headers.location!).then(resolve).catch(reject);
+          return;
+        }
+        if (res.statusCode !== 200) {
+          reject(new Error(`GitHub API returned ${res.statusCode} for ${url}`));
+          return;
+        }
+        let data = "";
+        res.on("data", (chunk) => (data += chunk));
+        res.on("end", () => {
+          try {
+            resolve(JSON.parse(data) as Record<string, unknown>);
+          } catch {
+            reject(new Error("Failed to parse GitHub API response"));
+          }
+        });
+      })
+      .on("error", reject);
+  });
+}
+
+function downloadFile(url: string, dest: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const doGet = (targetUrl: string) => {
+      https
+        .get(targetUrl, { headers: { "User-Agent": "create-amytis-cli" } }, (res) => {
+          if (res.statusCode === 301 || res.statusCode === 302) {
+            doGet(res.headers.location!);
+            return;
+          }
+          if (res.statusCode !== 200) {
+            reject(new Error(`Download failed with status ${res.statusCode}`));
+            return;
+          }
+          const file = fs.createWriteStream(dest);
+          res.pipe(file);
+          file.on("finish", () => file.close(() => resolve()));
+          file.on("error", (err) => {
+            fs.unlink(dest, () => {});
+            reject(err);
+          });
+        })
+        .on("error", reject);
+    };
+    doGet(url);
+  });
+}
+
+function extractTarball(tarPath: string, outDir: string): void {
+  // Extract into a temp dir, then move the inner folder out
+  const tmpDir = `${outDir}.__tmp__`;
+  fs.mkdirSync(tmpDir, { recursive: true });
+  execSync(`tar xzf "${tarPath}" -C "${tmpDir}"`);
+
+  // The tarball unpacks to a single top-level dir like "amytis-1.2.0/"
+  const entries = fs.readdirSync(tmpDir);
+  if (entries.length !== 1) {
+    throw new Error(`Unexpected tarball structure: ${entries.join(", ")}`);
+  }
+  const innerDir = path.join(tmpDir, entries[0]);
+  fs.renameSync(innerDir, outDir);
+  fs.rmdirSync(tmpDir);
+  fs.unlinkSync(tarPath);
+}
+
+// ---------------------------------------------------------------------------
+// Patch helpers
+// ---------------------------------------------------------------------------
+
+function escapeTemplateLiteral(str: string): string {
+  return str.replace(/\\/g, "\\\\").replace(/`/g, "\\`").replace(/\$\{/g, "\\${");
+}
+
+export function patchSiteConfig(projectDir: string, title: string, description: string): void {
+  const configPath = path.join(projectDir, "site.config.ts");
+  if (!fs.existsSync(configPath)) {
+    console.warn("  Warning: site.config.ts not found, skipping patch");
+    return;
+  }
+
+  let src = fs.readFileSync(configPath, "utf8");
+
+  // title: { en: "...", zh: "..." }
+  src = src.replace(
+    /title:\s*\{\s*en:\s*"[^"]*",\s*zh:\s*"[^"]*"\s*\}/,
+    `title: { en: ${JSON.stringify(title)}, zh: ${JSON.stringify(title)} }`
+  );
+
+  // description: { en: "...", zh: "..." }
+  src = src.replace(
+    /description:\s*\{\s*en:\s*"[^"]*",\s*zh:\s*"[^"]*"\s*\}/,
+    `description: { en: ${JSON.stringify(description)}, zh: ${JSON.stringify(description)} }`
+  );
+
+  // footerText — replace "Amytis" occurrences in template literals with project title
+  const safeTitle = escapeTemplateLiteral(title);
+  src = src.replace(
+    /footerText:\s*\{\s*en:\s*`[^`]*`,\s*zh:\s*`[^`]*`\s*\}/,
+    `footerText: { en: \`© \${new Date().getFullYear()} ${safeTitle}. All rights reserved.\`, zh: \`© \${new Date().getFullYear()} ${safeTitle}. 保留所有权利。\` }`
+  );
+
+  fs.writeFileSync(configPath, src, "utf8");
+}
+
+export function patchPackageJson(projectDir: string, projectName: string): void {
+  const pkgPath = path.join(projectDir, "package.json");
+  if (!fs.existsSync(pkgPath)) {
+    console.warn("  Warning: package.json not found, skipping patch");
+    return;
+  }
+
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8")) as Record<string, unknown>;
+
+  pkg["name"] = projectName;
+  pkg["private"] = true;
+  delete pkg["repository"];
+  delete pkg["bugs"];
+  delete pkg["homepage"];
+
+  fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf8");
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main(): Promise<void> {
+  console.log("\nCreate Amytis — scaffold a new digital garden\n");
+
+  // 1. Project name
+  let projectName = process.argv[2] ?? "";
+  if (!projectName) {
+    projectName = await prompt("Project name", "my-blog");
+  }
+
+  const targetDir = path.resolve(process.cwd(), projectName);
+  if (fs.existsSync(targetDir)) {
+    console.error(`Error: directory "${projectName}" already exists.`);
+    process.exit(1);
+  }
+
+  // 2. Fetch latest release tag
+  console.log("\nFetching latest Amytis release...");
+  const release = await fetchJson(
+    "https://api.github.com/repos/hutusi/amytis/releases/latest"
+  );
+  const tag = release["tag_name"] as string;
+  if (!tag) throw new Error("Could not determine latest release tag");
+  console.log(`  Found: ${tag}`);
+
+  // 3. Download tarball
+  const tarUrl = `https://github.com/hutusi/amytis/archive/refs/tags/${tag}.tar.gz`;
+  const tarDest = path.join(process.cwd(), `amytis-${tag}.tar.gz`);
+  console.log("Downloading tarball...");
+  await downloadFile(tarUrl, tarDest);
+
+  // 4. Extract
+  console.log("Extracting...");
+  extractTarball(tarDest, targetDir);
+  console.log(`  Scaffolded: ${targetDir}`);
+
+  // 5-6. Prompt for site metadata
+  const siteTitle = await prompt("\nSite title", projectName);
+  const siteDescription = await prompt(
+    "Site description",
+    "My digital garden"
+  );
+
+  // 7. Patch site.config.ts
+  console.log("\nPatching site.config.ts...");
+  patchSiteConfig(targetDir, siteTitle, siteDescription);
+
+  // 8. Patch package.json
+  console.log("Patching package.json...");
+  patchPackageJson(targetDir, projectName);
+
+  // 9. Run bun install
+  console.log("Installing dependencies (bun install)...");
+  execSync("bun install", { cwd: targetDir, stdio: "inherit" });
+
+  // 10. Success message
+  console.log(`
+Done! Your new Amytis site is ready.
+
+  cd ${projectName}
+  bun dev          # start the dev server at http://localhost:3000
+  bun run build    # production build
+
+Edit site.config.ts to customise navigation, themes, and more.
+Happy gardening!
+`);
+}
+
+if (import.meta.main) {
+  main().catch((err) => {
+    console.error("\nError:", (err as Error).message);
+    process.exit(1);
+  });
+}

package/packages/create-amytis/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"],
+  "exclude": ["src/**/*.test.ts"]
+}