@getguru/import-engine 0.0.0-stage → 0.1.0

package/LICENSE.md

@@ -0,0 +1,78 @@
+# License
+
+**@getguru/import-engine — Proprietary Software License**
+
+Copyright © 2026 Guru Technologies, Inc. All rights reserved.
+
+This software ("Software") is the proprietary property of Guru Technologies,
+Inc. ("Guru"). By installing, copying, or otherwise using the Software, you
+agree to the terms below. If you do not agree, do not install or use the
+Software.
+
+## 1. Grant of Use
+
+Subject to the terms of this license and a valid, active Guru subscription,
+Guru grants you a limited, non-exclusive, non-transferable, revocable license
+to install and use the Software solely to interact with Guru's services in
+connection with that subscription.
+
+## 2. Restrictions
+
+You may not:
+
+1. Redistribute, sublicense, rent, lease, sell, or otherwise transfer the
+   Software or its compiled artifacts, in whole or in part, to any third party.
+2. Modify, adapt, translate, reverse-engineer, decompile, disassemble, or
+   otherwise attempt to derive the source code of the Software, except to the
+   extent such restrictions are prohibited by applicable law.
+3. Create derivative works based on the Software.
+4. Use the Software to develop, train, or evaluate a product or service that
+   competes with Guru's services.
+5. Remove, alter, or obscure any proprietary notices (including copyright and
+   trademark notices) contained in or on the Software.
+
+## 3. Ownership
+
+The Software is licensed, not sold. Guru retains all right, title, and
+interest in and to the Software, including all intellectual property rights.
+No rights are granted to you other than those expressly set forth in this
+license.
+
+## 4. Disclaimer of Warranty
+
+THE SOFTWARE IS PROVIDED "AS IS" AND "AS AVAILABLE", WITHOUT WARRANTY OF ANY
+KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. GURU
+DOES NOT WARRANT THAT THE SOFTWARE WILL BE ERROR-FREE OR UNINTERRUPTED.
+
+## 5. Limitation of Liability
+
+TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL GURU BE
+LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR PUNITIVE
+DAMAGES, OR ANY LOSS OF PROFITS OR REVENUES, ARISING OUT OF OR RELATED TO YOUR
+USE OF, OR INABILITY TO USE, THE SOFTWARE, WHETHER BASED IN CONTRACT, TORT,
+STRICT LIABILITY, OR OTHERWISE, EVEN IF GURU HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+## 6. Termination
+
+This license terminates automatically upon (a) the termination or expiration
+of your Guru subscription, or (b) your material breach of any term of this
+license. Upon termination, you must cease all use of the Software and destroy
+all copies in your possession or control. Sections 3, 4, 5, and 7 survive
+termination.
+
+## 7. Governing Law
+
+This license is governed by and construed in accordance with the laws of the
+jurisdiction in which Guru Technologies, Inc. is headquartered, without regard
+to its conflict-of-laws principles.
+
+## 8. Contact
+
+Questions about this license may be directed to Guru Technologies, Inc.
+
+---
+
+**Trademarks.** "Guru" and related marks are trademarks of Guru Technologies,
+Inc. Nothing in this license grants any right to use such marks.

package/README.md

@@ -1,3 +1,75 @@
-# Temporary Holding Version
+# @getguru/import-engine
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Guru content importer as a command-line tool. It turns an export (Notion, Confluence,
+Google Sites, Google Docs, Word, PDF, Slab, GitHub wiki, Markdown, spreadsheet) into a zip
+that Guru can import. It is the same pipeline as the webapp's "Import content" screen,
+built from `guru-labs`.
+
+Requires Node >=22.
+
+## Usage
+
+```bash
+# build an import zip
+guru-import-engine <export> --type <import-type> --output <out.zip> [--split h1|h1,h2|none] [--json <path|->]
+
+# guess an export's import type (never builds anything)
+guru-import-engine --detect <export> [--json <path|->]
+
+# check the structure of a Guru import zip (not a source export)
+guru-import-engine --validate <guru-import.zip> [--json <path|->]
+```
+
+- `--type` is the import type (`notion`, `confluence`, `google-sites`, `google-doc`,
+  `word-doc`, `pdf`, `slab`, `github`, `markdown`, `spreadsheet`).
+- `--output` defaults to `guru-doc-import.zip`.
+- `--json <path|->` also writes a machine-readable report; `-` sends it to stdout and moves
+  the human-readable output to stderr.
+
+Without installing: `npx @getguru/import-engine --detect <export>`.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success (`--validate`: no errors; `--detect`: a result was printed, including `unknown`). |
+| 1 | The zip was built but some pages failed; `--validate`: the zip has errors. |
+| 2 | No zip was produced, or the input was unreadable (also if the `--json` file can't be written). The message goes to stderr. |
+| 64 | Usage error (bad or missing flag or value). |
+
+## `--json` report
+
+Every JSON document has `schemaVersion` (currently `1`; bumped on a breaking change).
+
+- Import (`<export> --json`): the import report (`toolVersion`, `importType`,
+  `exportFilename`, counts such as `cardCount`, `skippedCount`, `failedCount`,
+  `degradedCount`, `missingImageCount`, and the `failedDocs`, `skippedDocs`,
+  `missingImageDocs`, `unimportedFiles` and `signatures` lists), plus `inputFilename` and
+  `outputPath` (absolute path of the zip).
+- `--validate`: `errors`, `warnings`, `infos`, `syncErrors` counts, `looksLikeGuruImportZip`,
+  and `findings` (`{ severity, file, message }`).
+- `--detect`: `inputFilename`, `likely`, `confidence`, `evidence`, `alternatives`, `counts`.
+- Exit code 2: `{ schemaVersion, error: { message } }` at the same destination.
+
+The JSON holds page titles and snippets from the export. Treat it as customer data.
+
+## Releasing
+
+- Bump `version` in this `package.json`. It is also the engine version the import report
+  records in its tool version (`<version>+<short commit SHA>`).
+- CI publishes from `master` through npm trusted publishing.
+- The first publish (0.1.0) is done by hand from `master` after the merge, by a maintainer of
+  the `@getguru` npm scope:
+
+  ```bash
+  bash run.sh package && npm publish ./dist/import-engine --access public
+  ```
+
+  That maintainer then adds guru-labs's CircleCI project and the `guru-labs-npm-publish`
+  context as the trusted publisher for the package on npmjs.com. Assumption to confirm
+  against npm's trusted-publishing docs: the package must exist before a trusted publisher
+  can be configured, which is why the first publish is manual.
+
+## License
+
+Proprietary; see `LICENSE.md`.