expediate 1.0.3 → 1.0.5

package/dist/cjs/apis.js

@@ -0,0 +1,327 @@
+/* Copyright 2021 Fabien Bavent
+ *
+ * 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.
+ */
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.apiBuilder = apiBuilder;
+const router_js_1 = require("./router.js");
+const openapi_js_1 = require("./openapi.js");
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Instantiate a new service module for the given scope `key` and await its
+ * setup lifecycle hook.
+ *
+ * The lifecycle is:
+ * 1. **`data(key)`** — create the initial data object (`Partial<TInstance>`);
+ *    methods are mixed in next to complete the shape.
+ * 2. **Mix in methods** — each entry in `service.methods` is copied onto the
+ *    instance as a regular function bound to `this = instance`.
+ * 3. **`await setup()`** — if `setup` returns a `Promise`, it is fully
+ *    awaited before the instance is returned.  Any rejection propagates to
+ *    the caller.
+ *
+ * @param service - The service definition.
+ * @param key     - The scope key (`'singleton'`, `null`, or a session ID).
+ * @returns A Promise resolving to a fully initialised service instance.
+ */
+async function buildModule(service, key) {
+    // `data()` returns Partial<TInstance>; methods are mixed in below to complete
+    // the instance shape.  The cast is intentional and safe — by the time this
+    // function returns the instance IS a full TInstance.
+    const instance = service.data
+        ? service.data(key)
+        : { $key: key };
+    // Mix service methods into the instance, bound to `this = instance`.
+    // Regular function expressions are used (not arrow functions) so that each
+    // method has its own `arguments` object and `this` binding works correctly.
+    if (service.methods) {
+        for (const methodName of Object.keys(service.methods)) {
+            const method = service.methods[methodName];
+            instance[methodName] = function (...args) {
+                return method.apply(instance, args);
+            };
+        }
+    }
+    // Await setup so that async initialisation (DB connections, config fetches,
+    // etc.) completes before the instance is considered ready.
+    if (service.setup)
+        await service.setup.apply(instance, []);
+    return instance;
+}
+/**
+ * Resolve the correct service instance for an incoming request.
+ *
+ * Instance lifecycle by scope:
+ * - **Singleton** (`scope` absent): always returns `modules['singleton']`.
+ *   The singleton is guaranteed to be fully initialised before routes run,
+ *   so this path is synchronous within the async wrapper.
+ * - **Keyed** (`scope` returns a string): look up `modules[key]`; on first
+ *   access, build and cache the instance (in-flight builds for the same key
+ *   are deduplicated via `building` to avoid concurrent double-builds).
+ * - **Ephemeral** (`scope` returns `null`): create a fresh, uncached instance
+ *   for every request.
+ *
+ * @param service  - The service definition.
+ * @param modules  - The resolved-instance cache (mutated on first keyed access).
+ * @param building - In-flight build-promise cache; prevents duplicate builds
+ *                   for the same key under concurrent requests.
+ * @param req      - The incoming request.
+ * @returns A Promise resolving to the service instance for this request.
+ */
+async function resolveInstance(service, modules, building, req) {
+    if (typeof service.scope !== 'function') {
+        // Singleton — routes only run after setup is complete, so this is safe.
+        return modules['singleton'];
+    }
+    const key = service.scope(req);
+    if (key === null) {
+        // Ephemeral — create a fresh, uncached instance for every request.
+        return buildModule(service, null);
+    }
+    // Keyed — retrieve from resolved cache or initiate (and deduplicate) a build.
+    if (modules[key])
+        return modules[key];
+    if (!building[key]) {
+        building[key] = buildModule(service, key).then(instance => {
+            modules[key] = instance;
+            delete building[key];
+            return instance;
+        });
+    }
+    return building[key];
+}
+// ---------------------------------------------------------------------------
+// Response helpers
+// ---------------------------------------------------------------------------
+/**
+ * Send a JSON response with the appropriate `Content-Type` header.
+ *
+ * @param res  - The outgoing response.
+ * @param data - Any JSON-serialisable value.
+ */
+function sendJson(res, data) {
+    res.setHeader('Content-Type', 'application/json; charset=utf-8');
+    res.send(JSON.stringify(data));
+}
+/**
+ * Translate a caught error (thrown or rejected by a service method) into an
+ * HTTP error response.
+ *
+ * Expected shape: `{ status?, data?, message? }` (see {@link ApiError}).
+ * Any other thrown value is treated as an opaque 500 Internal Server Error.
+ *
+ * @param res - The outgoing response.
+ * @param err - The caught value.
+ */
+function sendError(res, err) {
+    const e = err;
+    const status = e?.status ?? 500;
+    if (e?.data !== undefined) {
+        res.setHeader('Content-Type', 'application/json; charset=utf-8');
+        res.status(status).send(JSON.stringify(e.data));
+    }
+    else {
+        res.status(status).send(e?.message ?? 'Internal error');
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Build an Express-compatible router from a service definition object.
+ *
+ * The returned router is suitable for mounting via `app.use()`:
+ *
+ * ```ts
+ * import myService from './my-service.js';
+ *
+ * app.use('/api', apiBuilder(myService));
+ * ```
+ *
+ * **Singleton setup lifecycle:**
+ * When `service.scope` is absent the service is a singleton.  The framework
+ * pre-builds the instance eagerly and registers a **503 Service not ready**
+ * guard middleware on the router immediately.  Route handlers are registered
+ * only once `setup()` resolves (or immediately, for sync setup).  Any request
+ * that arrives before setup completes receives a 503 response.
+ *
+ * **Keyed / ephemeral setup lifecycle:**
+ * Route handlers are registered immediately.  For each request,
+ * `resolveInstance()` is awaited inside the handler, so `setup()` is always
+ * complete before the service method is invoked.
+ *
+ * **Route handlers** declared in `service.GET`, `service.POST`, etc. are
+ * called with `this` bound to the service instance.  They receive two
+ * arguments:
+ * 1. `params` — merged route + query-string parameters from `req.params`.
+ * 2. `body`   — the parsed request body from `req.body` (requires a
+ *    body-parsing middleware such as `json()` to run first).
+ *
+ * **Return values:**
+ * - A **truthy value** (or a `Promise` resolving to one) → serialised as JSON
+ *   with status `200 OK`.
+ * - A **falsy value** (`undefined`, `null`, `false`, `0`, `''`) or a
+ *   `Promise` resolving to one → `201 No Content` (useful for mutations).
+ *
+ * **Error handling:**
+ * - Throwing or rejecting with `{ status, message }` sends the
+ *   corresponding HTTP error.
+ * - Throwing or rejecting with `{ status, data }` sends the `data` object
+ *   as a JSON body.
+ * - Any other thrown value produces `500 Internal Server Error`.
+ *
+ * @param service - The service definition (see {@link ServiceDefinition}).
+ * @returns A router instance pre-configured with all declared routes.
+ */
+function apiBuilder(service) {
+    const api = (0, router_js_1.default)();
+    /** Resolved instance cache: populated once setup completes for a given key. */
+    const modules = {};
+    /** In-flight build promises: deduplicates concurrent keyed instance builds. */
+    const building = {};
+    /**
+     * Register all route handlers from a route map for a given HTTP method.
+     *
+     * Each handler:
+     * 1. Resolves the correct service instance (awaiting setup when needed).
+     * 2. Invokes the service method with `(params, body)`.
+     * 3. Sends the return value as JSON (or 201 if falsy).
+     * 4. Catches thrown / rejected {@link ApiError} objects and translates them
+     *    into the appropriate HTTP error response.
+     *
+     * @param routeMap - Map of path patterns to service methods (`undefined` = skip).
+     * @param register - Registers a handler on the router for the current HTTP method.
+     */
+    function buildRoutes(routeMap, register) {
+        if (!routeMap)
+            return;
+        // Sort routes by decreasing specificity so that more precise patterns
+        // (more segments, fewer parameters) are registered first in the router.
+        // Without this, a plain path like '/items' would match '/items/1' as a
+        // prefix and steal requests intended for '/items/:id'.
+        // Specificity = (segment count * 100) - (parameter count * 10).
+        const sortedPaths = Object.keys(routeMap).sort((a, b) => {
+            const score = (p) => {
+                const segs = p.split('/').filter(s => s.length > 0);
+                return segs.length * 100 - segs.filter(s => s.startsWith(':')).length * 10;
+            };
+            return score(b) - score(a) || b.localeCompare(a);
+        });
+        for (const path of sortedPaths) {
+            const method = routeMap[path];
+            register(path, (req, res) => {
+                const params = req.params;
+                const body = req.body;
+                // Await instance resolution (no-op microtask for singletons; may
+                // trigger async buildModule for keyed / ephemeral instances).
+                resolveInstance(service, modules, building, req)
+                    .then(instance => {
+                    const ret = method.apply(instance, [params, body]);
+                    if (ret instanceof Promise) {
+                        return ret
+                            .then(val => {
+                            if (val !== undefined && val !== null && val !== false && val !== 0 && val !== '')
+                                sendJson(res, val);
+                            else
+                                res.status(201).end();
+                        })
+                            .catch(err => sendError(res, err));
+                    }
+                    if (ret !== undefined && ret !== null && ret !== false && ret !== 0 && ret !== '')
+                        sendJson(res, ret);
+                    else
+                        res.status(201).end();
+                })
+                    .catch(err => sendError(res, err));
+            });
+        }
+    }
+    /** Convenience wrapper to register routes for all five HTTP verbs. */
+    function registerAllRoutes() {
+        buildRoutes(service.GET, (path, h) => api.get(path, h));
+        buildRoutes(service.POST, (path, h) => api.post(path, h));
+        buildRoutes(service.PUT, (path, h) => api.put(path, h));
+        buildRoutes(service.DELETE, (path, h) => api.delete(path, h));
+        buildRoutes(service.PATCH, (path, h) => api.patch(path, h));
+    }
+    if (typeof service.scope !== 'function') {
+        // ── Singleton ─────────────────────────────────────────────────────────
+        // Register a "not ready" guard first so that requests arriving while
+        // setup is in progress receive 503 rather than 404.
+        let ready = false;
+        api.use('/', (_req, res, next) => {
+            if (!ready) {
+                res.statusCode = 503;
+                res.end('Service not ready');
+                return;
+            }
+            next();
+        });
+        // Build the singleton asynchronously, then flip the guard and register
+        // routes.  Even for synchronous setup() functions, buildModule() is async
+        // (it uses await internally), so route registration happens in a microtask
+        // that runs before any I/O callbacks — routes are always in place by the
+        // time the first HTTP request can be processed.
+        buildModule(service, 'singleton')
+            .then(instance => {
+            modules['singleton'] = instance;
+            ready = true;
+            registerAllRoutes();
+        })
+            .catch(err => {
+            // setup() rejected — log the error; the guard permanently returns 503.
+            console.error('[apiBuilder] singleton setup() rejected:', err);
+        });
+    }
+    else {
+        // ── Keyed / ephemeral ─────────────────────────────────────────────────
+        // Register routes immediately.  Each handler awaits resolveInstance(),
+        // which in turn awaits buildModule() for first-time keyed instances.
+        registerAllRoutes();
+    }
+    // ── OpenAPI introspection ──────────────────────────────────────────────────
+    /**
+     * Generate an OpenAPI 3.1.0 document from the service definition.
+     * Delegates to {@link openApiSpec} from `openapi.ts`.
+     */
+    api.spec = function (opts) {
+        return (0, openapi_js_1.openApiSpec)(service, opts);
+    };
+    /**
+     * Return a middleware handler that serves the OpenAPI spec as JSON or YAML.
+     * The spec is generated once and cached on the first call to the returned handler.
+     */
+    api.specHandler = function (opts, format = 'json') {
+        let cached = null;
+        const contentType = format === 'yaml'
+            ? 'application/yaml; charset=utf-8'
+            : 'application/json; charset=utf-8';
+        return function (_req, res) {
+            if (!cached)
+                cached = (0, openapi_js_1.serializeSpec)((0, openapi_js_1.openApiSpec)(service, opts), format);
+            res.setHeader('Content-Type', contentType);
+            res.end(cached);
+        };
+    };
+    return api;
+}
+exports.default = apiBuilder;

package/dist/cjs/git.js

@@ -0,0 +1,293 @@
+/* Copyright 2021 Fabien Bavent
+ *
+ * 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.
+ */
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gitHandler = gitHandler;
+exports.gitCreate = gitCreate;
+const child_process_1 = require("child_process");
+const zlib_1 = require("zlib");
+const fs_1 = require("fs");
+// ---------------------------------------------------------------------------
+// PKT-LINE helpers
+// ---------------------------------------------------------------------------
+/**
+ * Encode a string as a Git PKT-LINE frame.
+ *
+ * The Git Smart HTTP protocol wraps each line in a 4-hex-digit length prefix
+ * that counts the total frame length (4 bytes for the prefix itself plus the
+ * payload bytes, **not** characters).
+ *
+ * @param str - The plain-text payload to wrap (must be ASCII or UTF-8).
+ * @returns The framed string, e.g. `"001e# service=git-upload-pack\n"`.
+ *
+ * @see https://git-scm.com/docs/pack-protocol#_pkt_line_format
+ *
+ * @example
+ * ```ts
+ * pktLine('# service=git-upload-pack\n')
+ * // → '001e# service=git-upload-pack\n'
+ * //    ^^^^  4 + 26 = 30 = 0x1e
+ * ```
+ */
+function pktLine(str) {
+    const byteLen = Buffer.byteLength(str, 'utf8') + 4; // +4 for the 4-char hex prefix itself
+    return byteLen.toString(16).padStart(4, '0') + str;
+}
+/**
+ * The Git PKT-LINE flush packet.
+ * Signals the end of a list of PKT-LINE records.
+ */
+const PKT_FLUSH = '0000';
+// ---------------------------------------------------------------------------
+// Middleware factory
+// ---------------------------------------------------------------------------
+/**
+ * Middleware factory that exposes a Git repository over the **Git Smart HTTP
+ * protocol** (read-only fetch / clone, via `git-upload-pack`).
+ *
+ * Mount this handler at the root of a repository-scoped path so that the two
+ * sub-paths it handles (`/info/refs` and `/git-upload-pack`) are reachable:
+ *
+ * ```ts
+ * app.use('/repos/:repo', gitHandler({
+ *   repository: (req) => path.join('/srv/git', req.params.repo + '.git'),
+ * }));
+ * ```
+ *
+ * **Supported endpoints:**
+ *
+ * | Method | Path               | Purpose                                      |
+ * |--------|--------------------|----------------------------------------------|
+ * | GET    | `/info/refs`       | Smart HTTP capability advertisement          |
+ * | POST   | `/git-upload-pack` | Pack-file negotiation and transfer           |
+ * | POST   | `/git-receive-pack`| Pack-file publish and transfer               |
+ *
+ * **Compression:** gzip-compressed POST bodies are transparently decompressed
+ * before being piped to `git-upload-pack`.
+ *
+ * @param opt - Handler configuration (see {@link GitHandlerOptions}).
+ * @returns An Express-compatible middleware function `(req, res) => void`.
+ * @throws {TypeError} When `opt.repository` is not a function.
+ */
+function gitHandler(opt) {
+    if (typeof opt.repository !== 'function')
+        throw new TypeError('gitHandler: opt.repository must be a function');
+    const gitHome = opt.gitPath ?? '';
+    return (req, res) => {
+        // Resolve the repository path for this request.
+        const gitDirectory = opt.repository(req);
+        if (!gitDirectory)
+            return void res.status(404).send('Repository not found');
+        const urlPath = req.path; // sub-path after the mount prefix
+        // ── GET /info/refs?service=git-xxxxxx-pack ──────────────────────────
+        if (req.method === 'GET' && urlPath === '/info/refs') {
+            let args = [];
+            const service = req.queries?.url?.service;
+            if (service === 'git-upload-pack')
+                args = buildArgs(opt, ['--stateless-rpc', '--advertise-refs', gitDirectory]);
+            else if (service === 'git-receive-pack')
+                args = [gitDirectory];
+            else
+                return void res.status(403).send(`Service ${service} is not supported`);
+            res.setHeader('Content-Type', `application/x-${service}-advertisement`);
+            res.setHeader('Cache-Control', 'no-cache');
+            // The Smart HTTP advertisement starts with a PKT-LINE service banner
+            // followed by a flush packet (0000), then the git-upload-pack output.
+            res.write(pktLine(`# service=${service}\n`));
+            res.write(PKT_FLUSH);
+            const proc = (0, child_process_1.spawn)(gitHome + service, args, {
+                env: { ...process.env, GIT_PROTOCOL: req.headers['git-protocol'] || '' },
+            });
+            proc.on('error', (err) => {
+                console.error(`[${service} GET] spawn error:`, err.message);
+                if (!res.writableEnded)
+                    res.status(500).send(`${service} unavailable: ${err.message}`);
+            });
+            proc.stdout.pipe(res);
+            proc.stdout.on('error', (err) => {
+                console.warn(`[${service} GET] stdout error:`, err.message);
+            });
+            proc.stderr.on('data', (d) => console.error(`[${service} GET]`, d.toString()));
+            proc.on('close', (code) => {
+                if (code !== 0) {
+                    console.error(`[${service} GET] exited with code ${code}`);
+                    if (!res.writableEnded)
+                        res.status(500).send(`${service} failed`);
+                }
+                // When code === 0, proc.stdout has already piped all data and called
+                // res.end() automatically (default pipe behaviour).
+            });
+            return;
+        }
+        // ── POST /git-upload-pack or /git-receive-pack ──────────────────────
+        if (req.method === 'POST' && (urlPath === '/git-upload-pack' || urlPath === '/git-receive-pack')) {
+            const contentType = req.headers['content-type'] || '';
+            const service = urlPath.substring(1);
+            if (contentType !== `application/x-${service}-request`)
+                return void res.status(415).send('Unsupported Media Type');
+            let args = [];
+            if (service === 'git-upload-pack')
+                args = buildArgs(opt, ['--stateless-rpc', gitDirectory]);
+            else if (service === 'git-receive-pack')
+                args = [gitDirectory];
+            else
+                return void res.status(403).send(`Service ${service} is not supported`);
+            res.setHeader('Content-Type', `application/x-${service}-result`);
+            res.setHeader('Cache-Control', 'no-cache');
+            const proc = (0, child_process_1.spawn)(gitHome + service, args, {
+                env: { ...process.env, GIT_PROTOCOL: req.headers['git-protocol'] || '' },
+            });
+            proc.on('error', (err) => {
+                console.error(`[${service} POST] spawn error:`, err.message);
+                if (!res.writableEnded)
+                    res.status(500).send(`${service} unavailable: ${err.message}`);
+            });
+            // Transparently decompress gzip-encoded request bodies.
+            const encoding = req.headers['content-encoding'];
+            if (encoding === 'gzip') {
+                const gunzip = (0, zlib_1.createGunzip)();
+                gunzip.on('error', (err) => {
+                    console.warn(`[${service} POST] gunzip error:`, err.message);
+                    if (!res.writableEnded)
+                        res.status(400).send('Failed to decompress request body');
+                });
+                req.pipe(gunzip).pipe(proc.stdin);
+            }
+            else {
+                req.pipe(proc.stdin);
+            }
+            proc.stdout.pipe(res);
+            proc.stdout.on('error', (err) => {
+                console.warn(`[${service} POST] stdout error:`, err.message);
+            });
+            proc.stderr.on('data', (d) => console.error(`[${service} POST]`, d.toString()));
+            proc.on('close', (code) => {
+                if (code !== 0) {
+                    console.error(`[${service} POST] exited with code ${code}`);
+                    if (!res.writableEnded)
+                        res.status(500).send(`${service} failed`);
+                }
+            });
+            proc.stdin.on('error', (err) => {
+                // EPIPE is expected when the client disconnects mid-stream; it is not
+                // a server-side fault and does not require an error response.
+                if (err.code !== 'EPIPE')
+                    console.warn(`[${service} POST] stdin error:`, err.message);
+            });
+            return;
+        }
+        // Unrecognised path inside the repository mount.
+        res.status(404).send('Not found');
+    };
+}
+/**
+ * Initialise a new Git repository at `gitDirectory` by running `git init`.
+ *
+ * By default a **bare** repository is created (no working tree), which is the
+ * conventional layout for server-side hosting.  Pass `{ bare: false }` to
+ * create a standard repository with a working tree instead.
+ *
+ * @param gitDirectory - Absolute filesystem path of the directory in which
+ *   the repository will be created.  The directory is created by Git if it
+ *   does not already exist.
+ * @param opt - Creation options.  All fields are optional.
+ * @param opt.gitPath - Directory containing the `git` binary (with trailing
+ *   separator).  Defaults to `''` so that the system `PATH` is used.
+ * @param opt.bare - When `true` (default) a bare repository is created
+ *   (`git init --bare`).  When `false` a regular working-tree repository is
+ *   created (`git init`).
+ * @param opt.description - Text written to the repository's `description`
+ *   file after initialisation.  Bare: `<gitDirectory>/description`;
+ *   non-bare: `<gitDirectory>/.git/description`.  Skipped when omitted.
+ * @returns A `Promise` that resolves when the repository has been
+ *   successfully created, or rejects with an error message string when the
+ *   `git` process fails to start or exits with a non-zero code.
+ *
+ * @example
+ * ```ts
+ * // Create a bare repository (default — suitable for server hosting)
+ * await gitCreate('/srv/git/myproject.git', { description: 'My project' });
+ *
+ * // Create a regular repository with a working tree
+ * await gitCreate('/home/user/myproject', { bare: false });
+ * ```
+ */
+function gitCreate(gitDirectory, opt) {
+    return new Promise((resolve, reject) => {
+        const gitHome = opt.gitPath ?? '';
+        const isBare = opt.bare !== false; // default true
+        const args = isBare
+            ? ['init', '--bare', gitDirectory]
+            : ['init', gitDirectory];
+        const proc = (0, child_process_1.spawn)(gitHome + 'git', args, {
+            env: { ...process.env },
+        });
+        proc.on('error', (err) => {
+            console.error(`[git init] spawn error:`, err.message);
+            reject(`git unavailable: ${err.message}`);
+        });
+        proc.stdout.on('error', (err) => {
+            console.warn(`[git init] stdout error:`, err.message);
+        });
+        proc.stderr.on('data', (d) => console.error(`[git init]`, d.toString()));
+        proc.on('close', (code) => {
+            if (code !== 0) {
+                return reject('git failed');
+            }
+            if (opt.description) {
+                // Bare repos store the description at the root; working-tree repos
+                // store it inside the hidden .git sub-directory.
+                const descPath = isBare
+                    ? `${gitDirectory}/description`
+                    : `${gitDirectory}/.git/description`;
+                (0, fs_1.writeFileSync)(descPath, opt.description);
+            }
+            resolve();
+        });
+    });
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Build the argument list for `git-upload-pack`.
+ *
+ * Prepends an optional `--timeout=<n>` argument when configured, then
+ * inserts the `--strict` / `--no-strict` flag, followed by any additional
+ * arguments the caller provides.
+ *
+ * @param opt      - Handler options.
+ * @param trailing - Arguments appended after the strict flag
+ *                   (e.g. `['--stateless-rpc', '--advertise-refs', dir]`).
+ * @returns The complete argument array ready for `spawn`.
+ */
+function buildArgs(opt, trailing) {
+    const args = [];
+    if (opt.timeout) {
+        const seconds = parseInt(String(opt.timeout), 10);
+        if (!isNaN(seconds) && seconds > 0)
+            args.push(`--timeout=${seconds}`);
+    }
+    if (!opt.strict)
+        args.push('--no-strict');
+    return [...args, ...trailing];
+}
+exports.default = gitHandler;