@shimabell06/cloud-arch-icon-browser 0.0.0

package/LICENSE

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

@@ -0,0 +1,113 @@
+# Cloud Arch Icon Browser
+
+> Pre-release: `v0.1.0` is in development.
+
+A local, browser-based viewer for Microsoft Azure Architecture Icons.
+
+Cloud Arch Icon Browser is an independent open-source project. It is not affiliated with, endorsed by, or sponsored by Microsoft.
+
+Microsoft Azure Architecture Icons are **not included** in this repository or npm package. Users download the latest official icon package directly from Microsoft and use those icons in accordance with Microsoft's terms.
+
+## Usage
+
+```bash
+npx @shimabell06/cloud-arch-icon-browser
+```
+
+The command starts a temporary HTTP server bound to `127.0.0.1` on an available port and opens the local web UI in the default browser. The ZIP selected by the user is processed locally and is not uploaded or persisted by the application.
+
+## MVP goals
+
+- Load a user-selected official Azure Architecture Icons ZIP.
+- Preserve and browse the ZIP folder hierarchy as categories.
+- Search icons with exact, prefix, substring, normalized, and fuzzy matching.
+- Preview SVG icons without modifying the original SVG.
+- Download individual original SVG files with their official filenames unchanged.
+- Run locally through `npx` with no automatic runtime network access.
+
+## Official icon package
+
+Download the latest package from Microsoft Learn:
+
+https://learn.microsoft.com/en-us/azure/architecture/icons/
+
+The app may provide manual links to Microsoft documentation, but it does not automatically download the icon package or contact Microsoft at runtime.
+
+## Project status
+
+The project includes a local browser UI and a React-independent core for ZIP validation, metadata/categories, search, lazy SVG previews, and original-file downloads. The UI supports local package selection/replacement, recursive category browsing, debounced search, responsive navigation, details dialogs, and keyboard interaction. The production localhost CLI/static server is implemented with loopback-only binding, Host/path validation, restrictive browser security headers, and clean shutdown behavior.
+
+Release-readiness automation covers Linux browser E2E/accessibility/visual regression, Linux build/package checks, Windows/macOS packaged CLI smoke tests, `npm pack` leak validation, Changesets release PRs, an OIDC npm release workflow, and a weekly Microsoft source-change watcher. The npm package name is `@shimabell06/cloud-arch-icon-browser`; publication is activated with `private: false`. The current official `Azure_Public_Service_Icons_V24.zip` has passed the production-parser compatibility verification recorded in [`COMPATIBILITY.md`](./COMPATIBILITY.md). The remaining first-publication work is the one-time npm registry bootstrap and Trusted Publisher configuration described in [`docs/RELEASE.md`](./docs/RELEASE.md).
+
+See the [core integration notes](./docs/icon-package-core.md) for its API and validation boundaries and [`docs/RELEASE.md`](./docs/RELEASE.md) for the release/bootstrap runbook.
+
+## Development
+
+Supported Node.js versions are defined by `package.json`:
+
+```text
+^22.22.2 || ^24.15.0 || >=26.0.0
+```
+
+Node 25.x is intentionally unsupported by the current dependency set. For reproducible local development and CI, use the exact version in [`.node-version`](./.node-version), currently Node 24.20.0.
+
+With nvm:
+
+```bash
+nvm install 24.20.0
+nvm use 24.20.0
+npm ci
+npm run dev
+```
+
+Open the URL printed by Vite. Development and preview servers bind to `127.0.0.1`. Geist Sans Variable and all UI dependencies are bundled locally; the only external link in the shell opens Microsoft Learn when clicked.
+
+Core validation commands:
+
+```bash
+npm run check
+npm run typecheck
+npm test
+npm run build
+npm run test:cli-smoke
+npm run test:cli-package-smoke
+npm run verify:package
+npm run verify:release-ready
+```
+
+Browser E2E uses only the project-owned dummy ZIP fixture generated by `scripts/ui-review/create_fixture.py`:
+
+```bash
+python3 scripts/ui-review/create_fixture.py /tmp/cloud-arch-icon-browser-e2e-fixture.zip
+npx playwright install chromium
+E2E_FIXTURE=/tmp/cloud-arch-icon-browser-e2e-fixture.zip npm run test:e2e
+```
+
+`npm run test:e2e:update` updates the deliberately small Linux visual baseline set and should only be used when an intentional visual change has been reviewed.
+
+To verify a maintainer-downloaded current official ZIP without committing it:
+
+```bash
+npm run verify:official -- /path/to/latest-official.zip
+```
+
+`check:fix` applies Biome fixes; `test:watch` runs Vitest interactively. `build` typechecks the project, writes the Web UI to `dist/`, and compiles the production CLI to `cli/`. After a build, `node cli/index.js` exercises the same localhost server path that the package binary uses. `preview` is a Vite development tool for inspecting the Web build and is not the production CLI/server.
+
+## Project documents
+
+See:
+
+- [`DESIGN.md`](./DESIGN.md) — product and architecture source of truth.
+- [`AGENTS.md`](./AGENTS.md) — repository instructions for coding agents.
+- [`COMPATIBILITY.md`](./COMPATIBILITY.md) — official package compatibility and verification status.
+- [`CONTRIBUTING.md`](./CONTRIBUTING.md) — contribution workflow.
+- [`docs/RELEASE.md`](./docs/RELEASE.md) — release, npm bootstrap, OIDC, and watcher runbook.
+- [`SECURITY.md`](./SECURITY.md) — vulnerability reporting policy.
+
+## License
+
+The source code for this project is licensed under the MIT License. See [`LICENSE`](./LICENSE).
+
+Third-party software and assets retain their own licenses. See [`THIRD_PARTY_NOTICES.md`](./THIRD_PARTY_NOTICES.md).
+
+Microsoft Azure Architecture Icons are Microsoft assets and are not covered by this project's MIT License.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,59 @@
+# Third-Party Notices
+
+This project depends on third-party open-source software. Dependency licenses remain the property of their respective copyright holders and are not replaced by this project's MIT License.
+
+## Bundled notices and assets
+
+### Geist
+
+The application bundles Geist Sans Variable through the exact-pinned `@fontsource-variable/geist` 5.3.0 dependency. Vite emits the font files into the local build; no font CDN is used at runtime.
+
+Geist is distributed under the SIL Open Font License 1.1 (OFL-1.1). The font files are third-party assets and are not licensed under this project's MIT License. The upstream copyright notice and full OFL text are retained verbatim in [`public/licenses/Geist-OFL-1.1.txt`](./public/licenses/Geist-OFL-1.1.txt) and copied by Vite to `dist/licenses/Geist-OFL-1.1.txt`, which is included in the npm package.
+
+### shadcn/ui-derived component
+
+`src/components/ui/button.tsx` is derived from the official shadcn/ui Base UI Rhea registry. Copyright (c) 2023 shadcn. The upstream MIT license is retained in [`public/licenses/shadcn-MIT.txt`](./public/licenses/shadcn-MIT.txt) and copied into `dist/licenses/` by Vite.
+
+### ZIP processing and search
+
+`@zip.js/zip.js` 2.11.1 is distributed under BSD-3-Clause. Its unmodified license is retained in [`public/licenses/zip.js-BSD-3-Clause.txt`](./public/licenses/zip.js-BSD-3-Clause.txt) and copied into `dist/licenses/`.
+
+Fuse.js 7.5.0 is distributed under Apache-2.0. Its unmodified license is retained in [`public/licenses/Fuse-Apache-2.0.txt`](./public/licenses/Fuse-Apache-2.0.txt) and copied into `dist/licenses/`.
+
+The core uses zip.js with its local JavaScript compression fallback. No remote worker, WASM resource, or search service is fetched at runtime.
+
+## Direct runtime dependency inventory
+
+The `v0.1.0` release line uses exact-pinned direct runtime dependencies:
+
+- `@base-ui/react` 1.8.0
+- `@fontsource-variable/geist` 5.3.0
+- `@zip.js/zip.js` 2.11.1
+- `class-variance-authority` 0.7.1
+- `clsx` 2.1.1
+- `fuse.js` 7.5.0
+- `lucide-react` 1.41.0
+- `open` 11.0.2
+- `react` 19.2.8
+- `react-dom` 19.2.8
+- `tailwind-merge` 3.6.0
+
+`open` is used only by the local CLI to ask the operating system to open the generated `127.0.0.1` URL in the user's default browser. It does not add an automatic external runtime network request.
+
+## Development and release tooling
+
+Development-only tooling is not intentionally shipped in the npm tarball. Direct tooling includes Biome, TypeScript, Vite/Tailwind, Vitest and Testing Library, Playwright 1.62.1, `@axe-core/playwright` 4.13.0, and `@changesets/cli` 2.29.7.
+
+`npm run verify:package` inspects `npm pack --dry-run --json` and fails if development/test directories, ZIP files, SVG assets, or non-allowlisted top-level paths would be published. Release CI also runs `npm audit --audit-level=high` before publication.
+
+When a bundled dependency is changed, refresh any copied upstream license text required by that dependency and update this notice when the distribution obligations change.
+
+## Microsoft Azure Architecture Icons
+
+Microsoft Azure Architecture Icons are **not third-party assets distributed by this project**. They are intentionally excluded from the repository, test fixtures, screenshots, and npm package.
+
+Users obtain the icon package directly from Microsoft:
+
+https://learn.microsoft.com/en-us/azure/architecture/icons/
+
+Those icons are Microsoft assets governed by Microsoft's published terms. This project's MIT License does not grant rights to Microsoft icons. The weekly maintenance watcher fetches only the Microsoft Learn HTML page and never downloads or republishes the icon ZIP/SVG assets.

package/cli/cli.js

@@ -0,0 +1,130 @@
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import open from "open";
+import { startStaticServer, } from "./server.js";
+const HELP_TEXT = `Cloud Arch Icon Browser
+
+Usage:
+  cloud-arch-icon-browser
+  cloud-arch-icon-browser --help
+  cloud-arch-icon-browser --version
+
+Options:
+  -h, --help       Show this help message
+  -v, --version    Show the package version
+`;
+export function parseCliArguments(args) {
+    if (args.length === 0) {
+        return { kind: "start" };
+    }
+    if (args.length === 1) {
+        const argument = args[0];
+        if (argument === "-h" || argument === "--help") {
+            return { kind: "help" };
+        }
+        if (argument === "-v" || argument === "--version") {
+            return { kind: "version" };
+        }
+    }
+    return { kind: "invalid", arguments: [...args] };
+}
+export async function readPackageVersion() {
+    const candidates = [
+        new URL("../package.json", import.meta.url),
+        new URL("../../package.json", import.meta.url),
+    ];
+    for (const packageJsonUrl of candidates) {
+        let packageJsonText;
+        try {
+            packageJsonText = await readFile(packageJsonUrl, "utf8");
+        }
+        catch (error) {
+            if (isMissingFileError(error))
+                continue;
+            throw error;
+        }
+        const packageJson = JSON.parse(packageJsonText);
+        if (!isRecord(packageJson) || typeof packageJson.version !== "string") {
+            throw new Error("package.json does not contain a valid version string.");
+        }
+        return packageJson.version;
+    }
+    throw new Error("Unable to locate package.json.");
+}
+export async function attemptBrowserOpen(url, opener = open, warn = (message) => process.stderr.write(message)) {
+    try {
+        await opener(url);
+    }
+    catch (error) {
+        warn(`Unable to open the default browser automatically: ${formatError(error)}\n` +
+            `Open ${url} manually to continue.\n`);
+    }
+}
+export async function runCli(args) {
+    const command = parseCliArguments(args);
+    if (command.kind === "help") {
+        process.stdout.write(HELP_TEXT);
+        return 0;
+    }
+    if (command.kind === "version") {
+        try {
+            process.stdout.write(`${await readPackageVersion()}\n`);
+            return 0;
+        }
+        catch (error) {
+            process.stderr.write(`Unable to read package version: ${formatError(error)}\n`);
+            return 1;
+        }
+    }
+    if (command.kind === "invalid") {
+        process.stderr.write(`Unsupported arguments: ${command.arguments.join(" ")}\n` +
+            "Run cloud-arch-icon-browser --help for supported options.\n");
+        return 1;
+    }
+    let server;
+    try {
+        const staticRoot = fileURLToPath(new URL("../dist/", import.meta.url));
+        server = await startStaticServer({ rootDirectory: staticRoot });
+    }
+    catch (error) {
+        process.stderr.write(`Unable to start local server: ${formatError(error)}\n`);
+        return 1;
+    }
+    process.stdout.write(`Cloud Arch Icon Browser: ${server.url}\n`);
+    installShutdownHandlers(server);
+    void attemptBrowserOpen(server.url);
+    return 0;
+}
+function installShutdownHandlers(server) {
+    let shuttingDown = false;
+    const shutdown = async () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        process.off("SIGINT", handleSignal);
+        process.off("SIGTERM", handleSignal);
+        try {
+            await server.close();
+        }
+        catch (error) {
+            process.stderr.write(`Unable to stop local server cleanly: ${formatError(error)}\n`);
+            process.exitCode = 1;
+        }
+    };
+    const handleSignal = () => {
+        void shutdown();
+    };
+    process.once("SIGINT", handleSignal);
+    process.once("SIGTERM", handleSignal);
+}
+function isMissingFileError(error) {
+    if (!(error instanceof Error) || !("code" in error))
+        return false;
+    return error.code === "ENOENT" || error.code === "ENOTDIR";
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function formatError(error) {
+    return error instanceof Error ? error.message : "Unknown error";
+}

package/cli/index.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { runCli } from "./cli.js";
+const exitCode = await runCli(process.argv.slice(2));
+if (exitCode !== 0) {
+    process.exitCode = exitCode;
+}

package/cli/server.js

@@ -0,0 +1,254 @@
+import { readFile, readdir, realpath } from "node:fs/promises";
+import { createServer, } from "node:http";
+import { extname, resolve, sep } from "node:path";
+const LOOPBACK_HOST = "127.0.0.1";
+const CONTENT_SECURITY_POLICY = [
+    "default-src 'self'",
+    "script-src 'self'",
+    "style-src 'self'",
+    "img-src 'self' blob: data:",
+    "font-src 'self'",
+    "connect-src 'self'",
+    "object-src 'none'",
+    "base-uri 'none'",
+    "frame-ancestors 'none'",
+    "form-action 'none'",
+].join("; ");
+const MIME_TYPES = new Map([
+    [".css", "text/css; charset=utf-8"],
+    [".gif", "image/gif"],
+    [".html", "text/html; charset=utf-8"],
+    [".ico", "image/x-icon"],
+    [".jpeg", "image/jpeg"],
+    [".jpg", "image/jpeg"],
+    [".js", "text/javascript; charset=utf-8"],
+    [".json", "application/json; charset=utf-8"],
+    [".map", "application/json; charset=utf-8"],
+    [".mjs", "text/javascript; charset=utf-8"],
+    [".png", "image/png"],
+    [".svg", "image/svg+xml"],
+    [".ttf", "font/ttf"],
+    [".txt", "text/plain; charset=utf-8"],
+    [".wasm", "application/wasm"],
+    [".webp", "image/webp"],
+    [".woff", "font/woff"],
+    [".woff2", "font/woff2"],
+]);
+export async function startStaticServer(options) {
+    const rootDirectory = await realpath(options.rootDirectory);
+    const staticAssets = await loadStaticAssets(rootDirectory);
+    let selectedPort = 0;
+    const server = createServer((request, response) => {
+        try {
+            handleRequest(request, response, staticAssets, selectedPort);
+        }
+        catch {
+            if (!response.headersSent) {
+                sendText(request, response, 500, "Internal Server Error\n");
+                return;
+            }
+            response.destroy();
+        }
+    });
+    server.on("clientError", (_error, socket) => {
+        if (socket.writable) {
+            socket.end("HTTP/1.1 400 Bad Request\r\nConnection: close\r\nContent-Length: 0\r\n\r\n");
+        }
+    });
+    await listenOnAvailablePort(server);
+    const address = server.address();
+    if (address === null || typeof address === "string") {
+        await closeServer(server);
+        throw new Error("Unable to determine the localhost server port.");
+    }
+    selectedPort = address.port;
+    const url = `http://${LOOPBACK_HOST}:${selectedPort}/`;
+    let closePromise = null;
+    return {
+        port: selectedPort,
+        url,
+        close: () => {
+            closePromise ??= closeServer(server);
+            return closePromise;
+        },
+    };
+}
+function handleRequest(request, response, staticAssets, port) {
+    applySecurityHeaders(response);
+    if (!isExpectedHost(request.headers.host, port)) {
+        sendText(request, response, 403, "Forbidden\n");
+        return;
+    }
+    if (request.method !== "GET" && request.method !== "HEAD") {
+        response.setHeader("Allow", "GET, HEAD");
+        sendText(request, response, 405, "Method Not Allowed\n");
+        return;
+    }
+    const relativePath = parseStaticPath(request.url);
+    if (relativePath === null) {
+        sendText(request, response, 400, "Bad Request\n");
+        return;
+    }
+    const asset = staticAssets.get(relativePath);
+    if (asset === undefined) {
+        sendText(request, response, 404, "Not Found\n");
+        return;
+    }
+    response.statusCode = 200;
+    response.setHeader("Content-Type", asset.contentType);
+    response.setHeader("Content-Length", String(asset.body.byteLength));
+    response.setHeader("Cache-Control", asset.cacheControl);
+    if (request.method === "HEAD") {
+        response.end();
+        return;
+    }
+    response.end(asset.body);
+}
+async function loadStaticAssets(rootDirectory) {
+    const assets = new Map();
+    await collectStaticAssets(rootDirectory, rootDirectory, [], assets);
+    if (!assets.has("index.html")) {
+        throw new Error("Static build output does not contain index.html.");
+    }
+    return assets;
+}
+async function collectStaticAssets(rootDirectory, currentDirectory, pathSegments, assets) {
+    const entries = await readdir(currentDirectory, { withFileTypes: true });
+    for (const entry of entries) {
+        const absolutePath = resolve(currentDirectory, entry.name);
+        if (!isWithinRoot(rootDirectory, absolutePath)) {
+            throw new Error("Static build output escaped its configured root.");
+        }
+        const nextSegments = [...pathSegments, entry.name];
+        if (entry.isSymbolicLink()) {
+            throw new Error("Static build output must not contain symbolic links.");
+        }
+        if (entry.isDirectory()) {
+            await collectStaticAssets(rootDirectory, absolutePath, nextSegments, assets);
+            continue;
+        }
+        if (!entry.isFile()) {
+            throw new Error("Static build output contains an unsupported file type.");
+        }
+        const canonicalPath = await realpath(absolutePath);
+        if (!isWithinRoot(rootDirectory, canonicalPath)) {
+            throw new Error("Static build output escaped its configured root.");
+        }
+        const relativePath = nextSegments.join("/");
+        const body = await readFile(canonicalPath);
+        assets.set(relativePath, {
+            body,
+            contentType: MIME_TYPES.get(extname(canonicalPath).toLowerCase()) ??
+                "application/octet-stream",
+            cacheControl: cacheControlFor(relativePath),
+        });
+    }
+}
+function parseStaticPath(rawUrl) {
+    if (rawUrl === undefined ||
+        !rawUrl.startsWith("/") ||
+        rawUrl.startsWith("//")) {
+        return null;
+    }
+    const queryIndex = rawUrl.indexOf("?");
+    const rawPath = queryIndex === -1 ? rawUrl : rawUrl.slice(0, queryIndex);
+    let decodedPath;
+    try {
+        decodedPath = decodeURIComponent(rawPath);
+    }
+    catch {
+        return null;
+    }
+    if (decodedPath.includes("\0") || decodedPath.includes("\\")) {
+        return null;
+    }
+    if (decodedPath.split("/").some((segment) => segment === "..")) {
+        return null;
+    }
+    if (decodedPath === "/") {
+        return "index.html";
+    }
+    const relativePath = decodedPath.slice(1);
+    return relativePath.length > 0 ? relativePath : null;
+}
+function isExpectedHost(hostHeader, port) {
+    if (hostHeader === undefined)
+        return false;
+    const normalizedHost = hostHeader.trim().toLowerCase();
+    return (normalizedHost === `${LOOPBACK_HOST}:${port}` ||
+        normalizedHost === `localhost:${port}`);
+}
+function isWithinRoot(rootDirectory, candidatePath) {
+    return (candidatePath === rootDirectory ||
+        candidatePath.startsWith(`${rootDirectory}${sep}`));
+}
+function cacheControlFor(relativePath) {
+    if (relativePath === "index.html") {
+        return "no-store";
+    }
+    if (/^assets\/.+-[A-Za-z0-9_-]{8,}\.[^/]+$/.test(relativePath)) {
+        return "public, max-age=31536000, immutable";
+    }
+    return "no-cache";
+}
+function applySecurityHeaders(response) {
+    response.setHeader("Content-Security-Policy", CONTENT_SECURITY_POLICY);
+    response.setHeader("Cross-Origin-Opener-Policy", "same-origin");
+    response.setHeader("Permissions-Policy", permissionsPolicy());
+    response.setHeader("Referrer-Policy", "no-referrer");
+    response.setHeader("X-Content-Type-Options", "nosniff");
+    response.setHeader("X-Frame-Options", "DENY");
+}
+function permissionsPolicy() {
+    return [
+        "accelerometer=()",
+        "camera=()",
+        "geolocation=()",
+        "gyroscope=()",
+        "magnetometer=()",
+        "microphone=()",
+        "payment=()",
+        "serial=()",
+        "usb=()",
+    ].join(", ");
+}
+function sendText(request, response, statusCode, body) {
+    applySecurityHeaders(response);
+    response.statusCode = statusCode;
+    response.setHeader("Content-Type", "text/plain; charset=utf-8");
+    response.setHeader("Content-Length", String(Buffer.byteLength(body)));
+    response.setHeader("Cache-Control", "no-store");
+    if (request.method === "HEAD") {
+        response.end();
+        return;
+    }
+    response.end(body);
+}
+function listenOnAvailablePort(server) {
+    return new Promise((resolvePromise, rejectPromise) => {
+        const handleError = (error) => {
+            server.off("listening", handleListening);
+            rejectPromise(error);
+        };
+        const handleListening = () => {
+            server.off("error", handleError);
+            resolvePromise();
+        };
+        server.once("error", handleError);
+        server.once("listening", handleListening);
+        server.listen({ host: LOOPBACK_HOST, port: 0 });
+    });
+}
+function closeServer(server) {
+    if (!server.listening)
+        return Promise.resolve();
+    return new Promise((resolvePromise, rejectPromise) => {
+        server.close((error) => {
+            if (error) {
+                rejectPromise(error);
+                return;
+            }
+            resolvePromise();
+        });
+    });
+}