@aopslab/domain-ops-docman 0.1.4

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,6 @@
+AOPS Community
+
+Copyright 2026 Mehmet Zeki Sönmez
+
+Licensed under the Apache License, Version 2.0.
+Source: https://github.com/eeemzs/aops-community

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './specs.js';
+export * from './tools.js';
+export * from './runner.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from './specs.js';
+export * from './tools.js';
+export * from './runner.js';

package/dist/runner.d.ts

@@ -0,0 +1 @@
+export declare function runDocmanTool(toolId: string, input: unknown): Promise<unknown>;

package/dist/runner.js

@@ -0,0 +1,324 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { Effect } from 'effect';
+import { config as loadDotEnv } from 'dotenv';
+import { createDocmanKitWithEnv, getDocmanKitEnvConfig } from '@aopslab/domain-kit-docman';
+const TOOL_DOCUMENT_DELETE_SAFE = 'docman-document-delete-safe';
+const TOOL_DOCUMENT_VERSION_DELETE_SAFE = 'docman-document-version-delete-safe';
+const TOOL_DOCUMENT_SECTION_LINK_USAGE_LIST = 'docman-document-section-link-usage-list';
+const TOOL_DOCUMENT_COMPOSE_INDEX = 'docman-document-compose-index';
+const TOOL_DOCUMENT_INDEX_BUILD = 'docman-document-index-build';
+const TOOL_DOCUMENT_INDEX_GET = 'docman-document-index-get';
+const TOOL_DOCUMENT_SUMMARY_BUILD = 'docman-document-summary-build';
+const TOOL_DOCUMENT_SUMMARY_GET = 'docman-document-summary-get';
+const TOOL_DOCUMENT_SEARCH = 'docman-document-search';
+const TOOL_DOCUMENT_ANSWER_PACK = 'docman-document-answer-pack';
+const TOOL_DOCUMENT_COMPOSE_FETCH = 'docman-document-compose-fetch';
+let envLoaded = false;
+let cachedServices = null;
+function normalizeNonEmpty(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function normalizePositiveInt(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed <= 0)
+        return undefined;
+    return parsed;
+}
+function normalizeRetrievalStrategy(value) {
+    const normalized = normalizeNonEmpty(value);
+    if (normalized === 'hybrid' || normalized === 'semantic' || normalized === 'lexical') {
+        return normalized;
+    }
+    return undefined;
+}
+function pickLocaleOptions(payload) {
+    const locale = normalizeNonEmpty(payload.locale);
+    const fallbackLocale = normalizeNonEmpty(payload.fallbackLocale);
+    return {
+        ...(locale ? { locale } : {}),
+        ...(fallbackLocale ? { fallbackLocale } : {}),
+    };
+}
+function toRecord(input) {
+    if (!input || typeof input !== 'object')
+        return {};
+    return input;
+}
+function loadEnvOnce() {
+    if (envLoaded)
+        return;
+    envLoaded = true;
+    const candidates = [
+        process.env.DOTENV_CONFIG_PATH,
+        process.env.DOCMAN_ENV_PATH,
+        path.resolve(process.cwd(), '.env'),
+        path.resolve(process.cwd(), '..', '.env'),
+        path.resolve(process.cwd(), '../..', '.env'),
+    ].filter(Boolean);
+    for (const candidate of candidates) {
+        if (!candidate)
+            continue;
+        if (!fs.existsSync(candidate))
+            continue;
+        loadDotEnv({ path: candidate, quiet: true });
+        break;
+    }
+}
+function parseToolId(toolId) {
+    const match = /^docman-(.+)-(list|get|create|update|delete)$/.exec(toolId);
+    if (!match)
+        return null;
+    return { entity: match[1], op: match[2] };
+}
+function toPascalCase(value) {
+    return value
+        .split('-')
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join('');
+}
+function toCamelCase(value) {
+    if (!value)
+        return value;
+    return value.charAt(0).toLowerCase() + value.slice(1);
+}
+function buildServiceKey(entity) {
+    return `${toCamelCase(toPascalCase(entity))}Service`;
+}
+function buildListMethod(entity) {
+    return `list${toPascalCase(entity)}s`;
+}
+function buildUpdateMethod(entity) {
+    return `update${toPascalCase(entity)}`;
+}
+function buildRemoveMethod(entity) {
+    return `remove${toPascalCase(entity)}`;
+}
+async function getServices() {
+    if (cachedServices)
+        return cachedServices;
+    cachedServices = (async () => {
+        loadEnvOnce();
+        const envConfig = getDocmanKitEnvConfig();
+        const { kit } = createDocmanKitWithEnv({
+            envConfig,
+            baseContext: { tenantId: envConfig.tenantId },
+        });
+        const services = await kit.createAll();
+        return services;
+    })();
+    return cachedServices;
+}
+export async function runDocmanTool(toolId, input) {
+    const payload = toRecord(input);
+    const id = normalizeNonEmpty(payload.id);
+    if (toolId === TOOL_DOCUMENT_DELETE_SAFE) {
+        if (!id)
+            throw new Error('missing_required_id');
+        const confirmName = normalizeNonEmpty(payload.confirmName);
+        if (!confirmName)
+            throw new Error('missing_required_confirm_name');
+        const services = await getServices();
+        const service = services.documentService;
+        if (!service || typeof service.removeDocumentSafe !== 'function') {
+            throw new Error('docman_method_missing: documentService.removeDocumentSafe');
+        }
+        return Effect.runPromise(service.removeDocumentSafe(id, confirmName));
+    }
+    if (toolId === TOOL_DOCUMENT_VERSION_DELETE_SAFE) {
+        if (!id)
+            throw new Error('missing_required_id');
+        const services = await getServices();
+        const service = services.documentVersionService;
+        if (!service || typeof service.removeDocumentVersionSafe !== 'function') {
+            throw new Error('docman_method_missing: documentVersionService.removeDocumentVersionSafe');
+        }
+        return Effect.runPromise(service.removeDocumentVersionSafe(id));
+    }
+    if (toolId === TOOL_DOCUMENT_SECTION_LINK_USAGE_LIST) {
+        const sectionId = normalizeNonEmpty(payload.sectionId);
+        if (!sectionId) {
+            throw new Error('missing_required_section_id');
+        }
+        const services = await getServices();
+        const service = services.documentSectionLinkService;
+        if (!service || typeof service.listDocumentSectionLinkUsageBySectionId !== 'function') {
+            throw new Error('docman_method_missing: documentSectionLinkService.listDocumentSectionLinkUsageBySectionId');
+        }
+        return Effect.runPromise(service.listDocumentSectionLinkUsageBySectionId(sectionId));
+    }
+    if (toolId === TOOL_DOCUMENT_COMPOSE_INDEX) {
+        const documentVersionId = normalizeNonEmpty(payload.documentVersionId);
+        if (!documentVersionId)
+            throw new Error('missing_required_document_version_id');
+        const services = await getServices();
+        const service = services.documentService;
+        if (!service || typeof service.buildDocumentIndex !== 'function') {
+            throw new Error('docman_method_missing: documentService.buildDocumentIndex');
+        }
+        return Effect.runPromise(service.buildDocumentIndex(documentVersionId, pickLocaleOptions(payload)));
+    }
+    if (toolId === TOOL_DOCUMENT_INDEX_BUILD || toolId === TOOL_DOCUMENT_INDEX_GET) {
+        const documentVersionId = normalizeNonEmpty(payload.documentVersionId);
+        if (!documentVersionId)
+            throw new Error('missing_required_document_version_id');
+        const services = await getServices();
+        const service = services.documentService;
+        const methodName = toolId === TOOL_DOCUMENT_INDEX_BUILD ? 'buildPersistedDocumentIndex' : 'getPersistedDocumentIndex';
+        if (!service || typeof service[methodName] !== 'function') {
+            throw new Error(`docman_method_missing: documentService.${methodName}`);
+        }
+        return Effect.runPromise(service[methodName]({
+            documentVersionId,
+            ...pickLocaleOptions(payload),
+        }));
+    }
+    if (toolId === TOOL_DOCUMENT_SUMMARY_BUILD || toolId === TOOL_DOCUMENT_SUMMARY_GET) {
+        const documentVersionId = normalizeNonEmpty(payload.documentVersionId);
+        if (!documentVersionId)
+            throw new Error('missing_required_document_version_id');
+        const services = await getServices();
+        const service = services.documentService;
+        const methodName = toolId === TOOL_DOCUMENT_SUMMARY_BUILD ? 'buildPersistedDocumentSummary' : 'getPersistedDocumentSummary';
+        if (!service || typeof service[methodName] !== 'function') {
+            throw new Error(`docman_method_missing: documentService.${methodName}`);
+        }
+        return Effect.runPromise(service[methodName]({
+            documentVersionId,
+            ...pickLocaleOptions(payload),
+        }));
+    }
+    if (toolId === TOOL_DOCUMENT_SEARCH) {
+        const documentVersionId = normalizeNonEmpty(payload.documentVersionId);
+        if (!documentVersionId)
+            throw new Error('missing_required_document_version_id');
+        const q = normalizeNonEmpty(payload.q);
+        if (!q)
+            throw new Error('missing_required_q');
+        const services = await getServices();
+        const service = services.documentService;
+        if (!service || typeof service.searchPersistedDocumentIndex !== 'function') {
+            throw new Error('docman_method_missing: documentService.searchPersistedDocumentIndex');
+        }
+        const parsedLimit = Number(payload.limit);
+        const limit = Number.isInteger(parsedLimit) && parsedLimit > 0 ? parsedLimit : undefined;
+        const retrievalStrategy = normalizeRetrievalStrategy(payload.retrievalStrategy);
+        return Effect.runPromise(service.searchPersistedDocumentIndex({
+            documentVersionId,
+            q,
+            ...(limit ? { limit } : {}),
+            ...(retrievalStrategy ? { retrievalStrategy } : {}),
+            ...pickLocaleOptions(payload),
+        }));
+    }
+    if (toolId === TOOL_DOCUMENT_ANSWER_PACK) {
+        const documentVersionId = normalizeNonEmpty(payload.documentVersionId);
+        if (!documentVersionId)
+            throw new Error('missing_required_document_version_id');
+        const q = normalizeNonEmpty(payload.q);
+        if (!q)
+            throw new Error('missing_required_q');
+        const services = await getServices();
+        const service = services.documentService;
+        if (!service || typeof service.getDocumentAnswerPack !== 'function') {
+            throw new Error('docman_method_missing: documentService.getDocumentAnswerPack');
+        }
+        const parsedLimit = Number(payload.limit);
+        const limit = Number.isInteger(parsedLimit) && parsedLimit > 0 ? parsedLimit : undefined;
+        const retrievalStrategy = normalizeRetrievalStrategy(payload.retrievalStrategy);
+        return Effect.runPromise(service.getDocumentAnswerPack({
+            documentVersionId,
+            q,
+            ...(limit ? { limit } : {}),
+            ...(retrievalStrategy ? { retrievalStrategy } : {}),
+            ...pickLocaleOptions(payload),
+        }));
+    }
+    if (toolId === TOOL_DOCUMENT_COMPOSE_FETCH) {
+        const documentVersionId = normalizeNonEmpty(payload.documentVersionId);
+        if (!documentVersionId)
+            throw new Error('missing_required_document_version_id');
+        const pageNumberRaw = payload.pageNumber;
+        const pageNumber = normalizePositiveInt(pageNumberRaw);
+        if (pageNumberRaw !== undefined && pageNumber === undefined) {
+            throw new Error('invalid_page_number');
+        }
+        const inputPayload = {
+            documentVersionId,
+            ...pickLocaleOptions(payload),
+        };
+        const sectionId = normalizeNonEmpty(payload.sectionId);
+        if (sectionId)
+            inputPayload.sectionId = sectionId;
+        const pageVersionId = normalizeNonEmpty(payload.pageVersionId);
+        if (pageVersionId)
+            inputPayload.pageVersionId = pageVersionId;
+        if (pageNumber !== undefined)
+            inputPayload.pageNumber = pageNumber;
+        const services = await getServices();
+        const service = services.documentService;
+        if (!service || typeof service.fetchComposedFragment !== 'function') {
+            throw new Error('docman_method_missing: documentService.fetchComposedFragment');
+        }
+        return Effect.runPromise(service.fetchComposedFragment(inputPayload));
+    }
+    const parsed = parseToolId(toolId);
+    if (!parsed) {
+        throw new Error(`unknown_docman_tool: ${toolId}`);
+    }
+    const entity = parsed.entity;
+    const services = await getServices();
+    const serviceKey = buildServiceKey(entity);
+    const service = services[serviceKey];
+    if (!service) {
+        throw new Error(`docman_service_not_found: ${serviceKey}`);
+    }
+    const data = payload.data;
+    const patch = payload.patch;
+    const filter = (payload.filter ?? {});
+    const options = payload.options;
+    if (parsed.op === 'list') {
+        const listMethod = buildListMethod(entity);
+        const fn = service[listMethod];
+        if (typeof fn !== 'function')
+            throw new Error(`docman_list_method_missing: ${listMethod}`);
+        return Effect.runPromise(fn.call(service, filter, options));
+    }
+    if (parsed.op === 'get') {
+        if (!id)
+            throw new Error('missing_required_id');
+        return Effect.runPromise(service.getById(id, options));
+    }
+    if (parsed.op === 'create') {
+        if (!data || typeof data !== 'object')
+            throw new Error('missing_required_data');
+        return Effect.runPromise(service.create(data));
+    }
+    if (parsed.op === 'update') {
+        if (!id)
+            throw new Error('missing_required_id');
+        if (!patch || typeof patch !== 'object')
+            throw new Error('missing_required_patch');
+        const updateMethod = buildUpdateMethod(entity);
+        const fn = service[updateMethod];
+        if (typeof fn !== 'function')
+            throw new Error(`docman_update_method_missing: ${updateMethod}`);
+        return Effect.runPromise(fn.call(service, id, patch));
+    }
+    if (parsed.op === 'delete') {
+        if (!id)
+            throw new Error('missing_required_id');
+        const removeMethod = buildRemoveMethod(entity);
+        const fn = service[removeMethod];
+        if (typeof fn !== 'function')
+            throw new Error(`docman_remove_method_missing: ${removeMethod}`);
+        return Effect.runPromise(fn.call(service, id));
+    }
+    throw new Error(`unsupported_docman_tool: ${toolId}`);
+}

package/dist/specs.d.ts

@@ -0,0 +1,2 @@
+import type { ToolingSpec } from './types.js';
+export declare const DOCMAN_TOOL_SPECS: ToolingSpec[];

package/dist/specs.js

@@ -0,0 +1,342 @@
+const optionId = () => ({
+    name: 'id',
+    flag: '--id',
+    valueHint: '<id>',
+    description: 'Entity id',
+    type: 'string',
+    required: true,
+});
+const optionFilter = () => ({
+    name: 'filter',
+    flag: '--filter',
+    valueHint: '<json>',
+    description: 'Filter object (matches fields)',
+    type: 'json',
+});
+const optionOptions = () => ({
+    name: 'options',
+    flag: '--options',
+    valueHint: '<json>',
+    description: 'Query options (limit/offset/sort).',
+    type: 'json',
+});
+const optionDocumentListOptions = () => ({
+    name: 'options',
+    flag: '--options',
+    valueHint: '<json>',
+    description: 'Query options (limit/offset/sort). For document list use {"includeVersionInfo": true} to include documentVersions.',
+    type: 'json',
+});
+const optionData = () => ({
+    name: 'data',
+    flag: '--data',
+    valueHint: '<json>',
+    description: 'Insert payload',
+    type: 'json',
+    required: true,
+});
+const optionPatch = () => ({
+    name: 'patch',
+    flag: '--patch',
+    valueHint: '<json>',
+    description: 'Patch payload',
+    type: 'json',
+    required: true,
+});
+const optionSectionId = () => ({
+    name: 'sectionId',
+    flag: '--section-id',
+    valueHint: '<uuid>',
+    description: 'Section id',
+    type: 'string',
+    required: true,
+});
+const optionSectionIdOptional = () => ({
+    name: 'sectionId',
+    flag: '--section-id',
+    valueHint: '<uuid>',
+    description: 'Section id',
+    type: 'string',
+});
+const optionPageVersionId = () => ({
+    name: 'pageVersionId',
+    flag: '--page-version-id',
+    valueHint: '<uuid>',
+    description: 'Page version id',
+    type: 'string',
+});
+const optionDocumentVersionId = () => ({
+    name: 'documentVersionId',
+    flag: '--document-version-id',
+    valueHint: '<uuid>',
+    description: 'Document version id',
+    type: 'string',
+    required: true,
+});
+const optionParsedGraph = () => ({
+    name: 'parsedGraph',
+    flag: '--parsed-graph',
+    valueHint: '<json>',
+    description: 'Parsed heading graph JSON payload.',
+    type: 'json',
+    required: true,
+});
+const optionImportOptions = () => ({
+    name: 'options',
+    flag: '--options',
+    valueHint: '<json>',
+    description: 'Heading import options.',
+    type: 'json',
+});
+const optionPageNumber = () => ({
+    name: 'pageNumber',
+    flag: '--page-number',
+    valueHint: '<number>',
+    description: 'Composed page number (1-based).',
+    type: 'number',
+});
+const optionLocale = () => ({
+    name: 'locale',
+    flag: '--locale',
+    valueHint: '<lang>',
+    description: 'Locale hint (example: tr, en, tr-TR).',
+    type: 'string',
+});
+const optionFallbackLocale = () => ({
+    name: 'fallbackLocale',
+    flag: '--fallback-locale',
+    valueHint: '<lang>',
+    description: 'Fallback locale hint.',
+    type: 'string',
+});
+const optionQuery = () => ({
+    name: 'q',
+    flag: '--q',
+    valueHint: '<text>',
+    description: 'Search query text.',
+    type: 'string',
+    required: true,
+});
+const optionLimit = () => ({
+    name: 'limit',
+    flag: '--limit',
+    valueHint: '<number>',
+    description: 'Maximum number of hits to return.',
+    type: 'number',
+});
+const optionRetrievalStrategy = () => ({
+    name: 'retrievalStrategy',
+    flag: '--retrieval-strategy',
+    valueHint: '<lexical|hybrid|semantic>',
+    description: 'Retrieval mode. Defaults to lexical when omitted.',
+    type: 'string',
+});
+const optionConfirmName = () => ({
+    name: 'confirmName',
+    flag: '--confirm-name',
+    valueHint: '<name>',
+    description: 'Type the exact document title to confirm deletion.',
+    type: 'string',
+    required: true,
+});
+const ENTITIES = [
+    { id: 'document', title: 'Document', description: 'Document record.' },
+    { id: 'document-group', title: 'Document group', description: 'Hierarchical grouping for documents.' },
+    { id: 'document-version', title: 'Document version', description: 'Version metadata for a document.' },
+    { id: 'section', title: 'Section', description: 'Section record.' },
+    { id: 'page', title: 'Page', description: 'Page record.' },
+    { id: 'page-version', title: 'Page version', description: 'Version metadata for a page.' },
+    { id: 'document-section-link', title: 'Document section link', description: 'Link between document version and section.' },
+    { id: 'section-page-link', title: 'Section page link', description: 'Link between section and page version.' },
+    { id: 'snippet', title: 'Snippet', description: 'Snippet record.' },
+    { id: 'page-snippet-link', title: 'Page snippet link', description: 'Link between page version and snippet.' },
+    { id: 'embed', title: 'Embed', description: 'Embed record.' },
+    { id: 'page-embed-link', title: 'Page embed link', description: 'Link between page version and embed.' },
+];
+const CRUD_OPS = [
+    {
+        op: 'list',
+        title: 'List',
+        description: 'List items by filter.',
+        result: 'list',
+        options: () => [optionFilter(), optionOptions()],
+    },
+    {
+        op: 'get',
+        title: 'Get',
+        description: 'Get item by id.',
+        result: 'action',
+        options: () => [optionId()],
+    },
+    {
+        op: 'create',
+        title: 'Create',
+        description: 'Create item.',
+        result: 'action',
+        options: () => [optionData()],
+    },
+    {
+        op: 'update',
+        title: 'Update',
+        description: 'Update item by id.',
+        result: 'action',
+        options: () => [optionId(), optionPatch()],
+    },
+    {
+        op: 'delete',
+        title: 'Delete',
+        description: 'Delete item by id.',
+        result: 'action',
+        options: () => [optionId()],
+    },
+];
+function buildSpecs(entity) {
+    const segments = entity.segments ?? entity.id.split('-');
+    return CRUD_OPS.map((op) => ({
+        id: `docman-${entity.id}-${op.op}`,
+        group: 'docman',
+        title: `${op.title} ${entity.title}`,
+        description: `${op.description} ${entity.description}`,
+        command: ['docman', ...segments, op.op],
+        result: op.result,
+        options: entity.id === 'document' && op.op === 'list' ? [optionFilter(), optionDocumentListOptions()] : op.options(),
+    }));
+}
+const SAFE_DELETE_SPECS = [
+    {
+        id: 'docman-document-delete-safe',
+        group: 'docman',
+        title: 'Delete Document Safely',
+        description: 'Delete a document with its versions and orphan-only section/page graph.',
+        command: ['docman', 'document', 'delete-safe'],
+        result: 'action',
+        options: [optionId(), optionConfirmName()],
+    },
+    {
+        id: 'docman-document-version-delete-safe',
+        group: 'docman',
+        title: 'Delete Document version Safely',
+        description: 'Delete a document version and orphan-only section/page graph.',
+        command: ['docman', 'document', 'version', 'delete-safe'],
+        result: 'action',
+        options: [optionId()],
+    },
+    {
+        id: 'docman-document-version-import-headings',
+        group: 'docman',
+        title: 'Import Document version Headings',
+        description: 'Import a parsed heading graph into one document version.',
+        command: ['docman', 'document', 'version', 'import-headings'],
+        result: 'action',
+        options: [optionDocumentVersionId(), optionParsedGraph(), optionImportOptions()],
+    },
+];
+const CUSTOM_SPECS = [
+    {
+        id: 'docman-document-section-link-usage-list',
+        group: 'docman',
+        title: 'List Section usage',
+        description: 'List document versions linked to a section.',
+        command: ['docman', 'document', 'section', 'usage', 'list'],
+        result: 'list',
+        options: [optionSectionId()],
+    },
+    {
+        id: 'docman-document-compose-index',
+        group: 'docman',
+        title: 'Build Document Compose Index',
+        description: 'Build index with sections/pages and dynamic composed pages.',
+        command: ['docman', 'document', 'compose', 'index'],
+        result: 'action',
+        options: [optionDocumentVersionId(), optionLocale(), optionFallbackLocale()],
+    },
+    {
+        id: 'docman-document-compose-fetch',
+        group: 'docman',
+        title: 'Fetch Composed Fragment',
+        description: 'Fetch composed source fragment with resolved asset references (document, section, or page).',
+        command: ['docman', 'document', 'compose', 'fetch'],
+        result: 'action',
+        options: [
+            optionDocumentVersionId(),
+            optionSectionIdOptional(),
+            optionPageVersionId(),
+            optionPageNumber(),
+            optionLocale(),
+            optionFallbackLocale(),
+        ],
+    },
+    {
+        id: 'docman-document-index-build',
+        group: 'docman',
+        title: 'Build Persisted Document Index',
+        description: 'Build persisted retrieval index rows for one document version.',
+        command: ['docman', 'document', 'index', 'build'],
+        result: 'action',
+        options: [optionDocumentVersionId(), optionLocale(), optionFallbackLocale()],
+    },
+    {
+        id: 'docman-document-index-get',
+        group: 'docman',
+        title: 'Get Persisted Document Index',
+        description: 'Read persisted retrieval index rows for one document version.',
+        command: ['docman', 'document', 'index', 'get'],
+        result: 'action',
+        options: [optionDocumentVersionId(), optionLocale(), optionFallbackLocale()],
+    },
+    {
+        id: 'docman-document-summary-build',
+        group: 'docman',
+        title: 'Build Persisted Document Summaries',
+        description: 'Build persisted document, section, and page summaries for one document version.',
+        command: ['docman', 'document', 'summary', 'build'],
+        result: 'action',
+        options: [optionDocumentVersionId(), optionLocale(), optionFallbackLocale()],
+    },
+    {
+        id: 'docman-document-summary-get',
+        group: 'docman',
+        title: 'Get Persisted Document Summaries',
+        description: 'Read persisted document, section, and page summaries for one document version.',
+        command: ['docman', 'document', 'summary', 'get'],
+        result: 'action',
+        options: [optionDocumentVersionId(), optionLocale(), optionFallbackLocale()],
+    },
+    {
+        id: 'docman-document-search',
+        group: 'docman',
+        title: 'Search Document Index',
+        description: 'Search persisted retrieval index rows for one document version.',
+        command: ['docman', 'document', 'search'],
+        result: 'action',
+        options: [
+            optionDocumentVersionId(),
+            optionQuery(),
+            optionLimit(),
+            optionRetrievalStrategy(),
+            optionLocale(),
+            optionFallbackLocale(),
+        ],
+    },
+    {
+        id: 'docman-document-answer-pack',
+        group: 'docman',
+        title: 'Get Document Answer Pack',
+        description: 'Get answer, citations, and provenance for one document version query.',
+        command: ['docman', 'document', 'answer-pack'],
+        result: 'action',
+        options: [
+            optionDocumentVersionId(),
+            optionQuery(),
+            optionLimit(),
+            optionRetrievalStrategy(),
+            optionLocale(),
+            optionFallbackLocale(),
+        ],
+    },
+];
+export const DOCMAN_TOOL_SPECS = [
+    ...ENTITIES.flatMap((entity) => buildSpecs(entity)),
+    ...SAFE_DELETE_SPECS,
+    ...CUSTOM_SPECS,
+];

package/dist/tools.d.ts

@@ -0,0 +1,7 @@
+import type { ToolingGroup } from './types.js';
+import { DOCMAN_TOOL_SPECS } from './specs.js';
+export type DocmanToolId = (typeof DOCMAN_TOOL_SPECS)[number]['id'];
+export declare const DOCMAN_TOOL_IDS: DocmanToolId[];
+export declare const DOCMAN_TOOL_GROUP: ToolingGroup;
+export declare function buildDocmanToolId(segments: string[]): string;
+export declare function isDocmanToolId(toolId: string): toolId is DocmanToolId;

package/dist/tools.js

@@ -0,0 +1,35 @@
+import { DOCMAN_TOOL_SPECS } from './specs.js';
+export const DOCMAN_TOOL_IDS = DOCMAN_TOOL_SPECS.map((spec) => spec.id);
+const DOCMAN_TOOL_ID_SET = new Set(DOCMAN_TOOL_IDS);
+export const DOCMAN_TOOL_GROUP = {
+    id: 'docman',
+    title: 'Docman tools',
+    toolIds: [...DOCMAN_TOOL_IDS],
+    notes: [
+        'Docman tools manage documents and hierarchical groups.',
+        'Use list filters or ids to target entities.',
+        'For list documents, use --options with {"includeVersionInfo": true} to include documentVersions.',
+        'MLG fields must be JSON objects (example: {"tr":"...","en":"..."}) and are stored as jsonb in DB.',
+        'Compose tools can build index, fetch fragments, and render markdown from document versions.',
+        'Create/update payloads are sent via data/patch fields (JSON).',
+        'Document groups can be nested via parentGroupId.',
+    ],
+    examples: [
+        'POST /api/agent/tools/docman-document-list/invoke {"input":{"filter":{"title":"Spec"}}}',
+        'POST /api/agent/tools/docman-document-list/invoke {"input":{"filter":{},"options":{"includeVersionInfo":true}}}',
+        'POST /api/agent/tools/docman-document-version-create/invoke {"input":{"data":{"documentId":"<documentId>","version":3,"status":"draft","releaseNotesMl":{"tr":"Surum notu","en":"Release note"}}}}',
+        'POST /api/agent/tools/docman-document-compose-index/invoke {"input":{"pathParams":{"id":"<documentVersionId>"},"body":{"options":{"locale":"tr","fallbackLocale":"en"}}}}',
+        'POST /api/agent/tools/docman-document-compose-fetch/invoke {"input":{"pathParams":{"id":"<documentVersionId>"},"body":{"pageNumber":2}}}',
+        'POST /api/agent/tools/docman-document-group-create/invoke {"input":{"data":{"title":"Application Notes"}}}',
+        'POST /api/agent/tools/docman-page-create/invoke {"input":{"data":{"pageUid":"PAG-1","title":"Introduction"}}}',
+        'POST /api/agent/tools/docman-document-update/invoke {"input":{"id":"<docId>","patch":{"groupId":"<groupId>"}}}',
+        'POST /api/agent/tools/docman-document-group-list/invoke {"input":{"filter":{"parentGroupId":"<groupId>"}}}',
+    ],
+};
+export function buildDocmanToolId(segments) {
+    const normalized = segments.map((segment) => segment.trim()).filter(Boolean);
+    return 'docman-' + normalized.join('-').toLowerCase();
+}
+export function isDocmanToolId(toolId) {
+    return DOCMAN_TOOL_ID_SET.has(toolId);
+}

package/dist/types.d.ts

@@ -0,0 +1,26 @@
+export type ToolingOptionType = 'string' | 'number' | 'boolean' | 'json';
+export type ToolingOptionSpec = {
+    name: string;
+    flag: string;
+    valueHint?: string;
+    description?: string;
+    type: ToolingOptionType;
+    required?: boolean;
+};
+export type ToolingResultKind = 'list' | 'action';
+export type ToolingSpec = {
+    id: string;
+    group: string;
+    title: string;
+    description: string;
+    command: string[];
+    result: ToolingResultKind;
+    options?: ToolingOptionSpec[];
+};
+export type ToolingGroup = {
+    id: string;
+    title: string;
+    toolIds: string[];
+    notes?: string[];
+    examples?: string[];
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@aopslab/domain-ops-docman",
+  "version": "0.1.4",
+  "type": "module",
+  "private": false,
+  "description": "Docman operational utilities (seed, maintenance, offline ops).",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    "./specs": {
+      "types": "./dist/specs.d.ts",
+      "import": "./dist/specs.js",
+      "default": "./dist/specs.js"
+    },
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!**/*.tsbuildinfo",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "dependencies": {
+    "dotenv": "^17.3.1",
+    "effect": "3.20.0",
+    "@aopslab/domain-kit-docman": "0.1.4"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eeemzs/docman.git",
+    "directory": "docman-ops"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.lib.json"
+  }
+}