📁 @saptools/sharepoint-check

Pre-flight SharePoint diagnostics for Microsoft Graph app-only access.

Verify auth, resolve the target site, inspect document libraries, walk folder trees, validate required paths, and dry-run write access before a pipeline or migration goes live.

Install • Quick Start • CLI • FAQ

✨ Features

• 🔐 App-only auth check: requests a client-credentials token, decodes the JWT locally, and shows the app id, tenant, roles, and scopes carried by the token
• 🧭 Site resolution: proves the target host/sites/... reference really maps to a SharePoint site before later steps fail more vaguely
• 🗂️ Drive discovery: lists every visible document library on the target site so you can confirm which drive the integration should use
• 🌲 Folder tree walk: traverses a folder and summarizes file counts, subfolder counts, and aggregate size per node
• ✅ Layout validation: checks that a required root path and expected subdirectories exist, with exit code 2 when validation fails
• ✍️ Write probe: creates and deletes a uniquely named folder to prove the app can actually write, not just read metadata
• 🧰 CLI and typed API: everything used by the CLI is exported for scripts and Node.js automation
• 🪶 Tiny runtime surface: one runtime dependency (commander), no MSAL SDK, no Graph SDK

📦 Install

# Global CLI
npm install -g @saptools/sharepoint-check

# Or as a dependency
npm install @saptools/sharepoint-check
# pnpm add @saptools/sharepoint-check
# yarn add @saptools/sharepoint-check

[!NOTE] Requires Node.js >= 20. The CLI binary is saptools-sharepoint-check.

Updates

Every command first checks npm for a newer @saptools/sharepoint-check (at most once an hour, one small request with a 2-second timeout) and, when one exists, installs that exact version with the package manager that owns the running binary and re-runs the command you typed on the new version. Both steps are announced on stderr; nothing is printed when the install is already current:

saptools-sharepoint-check: updating 0.2.0 -> 0.3.0 ...
saptools-sharepoint-check: updated to 0.3.0; re-running the command

If the install cannot complete, one stderr line gives the manual command and the command runs on the installed version; that version is not retried for a day. saptools-sharepoint-check self-update forces the check and install now; saptools-sharepoint-check self-update --check only reports.

| Control | Effect | | --- | --- | | SAPTOOLS_AUTO_UPDATE=on\|notify\|off | on (default) installs and re-runs; notify prints the manual command once per version; off never checks. Applies to every @saptools CLI. | | SHAREPOINT_CHECK_AUTO_UPDATE | same values, this CLI only; wins over the global variable | | SAPTOOLS_UPDATE_INTERVAL_MINUTES | minutes between checks (default 60; 0 checks on every run) | | SAPTOOLS_NPM_REGISTRY | registry to check and install from (default: npm's configured registry, then npmjs) | | SAPTOOLS_UPDATE_DEBUG=1 | explain on stderr why nothing happened |

The updater switches itself off in CI (CI set), under NODE_ENV=test or NO_UPDATE_NOTIFIER, when the binary runs from a source checkout, an npm link or an npx cache, and inside the re-run itself. It never writes to stdout, never asks for input, never uses sudo, and never moves onto a prerelease. Its state lives in ~/.saptools/updates/.

🚀 Quick Start

# 1. Export the required credentials and target site
export SHAREPOINT_TENANT_ID="11111111-1111-1111-1111-111111111111"
export SHAREPOINT_CLIENT_ID="22222222-2222-2222-2222-222222222222"
export SHAREPOINT_CLIENT_SECRET="<your-client-secret>"
export SHAREPOINT_SITE="contoso.sharepoint.com/sites/demo"

# 2. Optional defaults for validation / write checks
export SHAREPOINT_ROOT_DIR="Apps"
export SHAREPOINT_SUBDIRS="sample-app,demo-app"

# 3. Prove auth + site resolution
saptools-sharepoint-check test

# 4. See available document libraries
saptools-sharepoint-check drives

# 5. Run the full pre-flight check
saptools-sharepoint-check check --drive Documents --root Apps --subdirs "sample-app,demo-app"

Typical output:

✔ Authenticated: App: Demo Connector | AppId: 22222222-... | Tenant: 11111111-... | Roles: Sites.Selected
✔ Site: Demo Site — 2 drive(s) available
✔ Using drive: Documents
✔ root: Apps
✔ Apps/sample-app
✔ Apps/demo-app
All expected folders present.
✔ Write probe passed at Apps/sharepoint-check-probe-ms4k2-ae12...

🧰 CLI

Every subcommand reads auth from flags or environment variables:

| Flag | Env | Description | | --- | --- | --- | | --tenant <id> | SHAREPOINT_TENANT_ID | Azure AD tenant id | | --client-id <id> | SHAREPOINT_CLIENT_ID | App registration client id | | --client-secret <secret> | SHAREPOINT_CLIENT_SECRET | App registration client secret | | --site <ref> | SHAREPOINT_SITE | SharePoint site reference such as contoso.sharepoint.com/sites/demo | | --json | - | Machine-readable JSON output for test, drives, tree, validate, and write-test |

🔎 test

Acquire an app-only token and resolve the target site.

saptools-sharepoint-check test
saptools-sharepoint-check test --json | jq '.claims.roles'

Returns exit code 1 on auth, configuration, or site-resolution errors.

🗂️ drives

List document libraries visible on the site.

saptools-sharepoint-check drives
saptools-sharepoint-check drives --json

Use this first if you are unsure whether the right drive is named Documents, Shared Documents, or something custom.

🌲 tree

Walk a folder and print a summary tree.

saptools-sharepoint-check tree --drive Documents --root Apps
saptools-sharepoint-check tree --drive Documents --root Apps --depth 5 --json

| Flag | Env | Default | | --- | --- | --- | | --drive <nameOrId> | - | First drive on the site | | --root <path> | SHAREPOINT_ROOT_DIR | Drive root | | --depth <n> | - | 3 |

✅ validate

Check that a root folder and its expected subdirectories exist.

saptools-sharepoint-check validate --drive Documents --root Apps --subdirs "sample-app,demo-app"

| Flag | Env | Description | | --- | --- | --- | | --drive <nameOrId> | - | Drive name or id | | --root <path> | SHAREPOINT_ROOT_DIR | Root folder to validate | | --subdirs <list> | SHAREPOINT_SUBDIRS | Comma- or newline-separated expected subdirectories |

Returns exit code 2 when any expected folder is missing or is not a folder.

✍️ write-test

Create and delete a uniquely named probe folder under the chosen root.

saptools-sharepoint-check write-test --drive Documents --root Apps
saptools-sharepoint-check write-test --drive Documents --root Apps --json

The probe folder uses the prefix sharepoint-check-probe- plus a timestamp/random suffix, so concurrent runs do not collide.

Returns exit code 2 when create or cleanup fails.

🧪 check

Run the full diagnostic sequence in one pass:

1. authenticate
2. resolve site
3. list drives
4. validate required layout
5. run the write probe

saptools-sharepoint-check check --drive Documents --root Apps --subdirs "sample-app,demo-app"

check emits human-readable output only. It returns exit code 2 for layout/write failures and exit code 1 for fatal errors such as missing config or Graph failures.

🌐 Environment Variables

| Variable | Purpose | | --- | --- | | SHAREPOINT_TENANT_ID | Azure AD tenant id | | SHAREPOINT_CLIENT_ID | App registration client id | | SHAREPOINT_CLIENT_SECRET | Client secret | | SHAREPOINT_SITE | Site reference such as contoso.sharepoint.com/sites/demo | | SHAREPOINT_ROOT_DIR | Default root for tree, validate, write-test, and check | | SHAREPOINT_SUBDIRS | Expected subdirectories, comma- or newline-separated | | SHAREPOINT_AUTH_BASE | Override the Azure AD auth host, mainly for tests | | SHAREPOINT_GRAPH_BASE | Override the Graph base URL, mainly for tests |

🚦 Exit Codes

| Code | Meaning | | --- | --- | | 0 | Success | | 1 | Fatal error such as missing config, auth failure, invalid input, or Graph error | | 2 | Validation failure or write probe failure |

❓ FAQ

Use the site root, not a deep page URL. Good examples:

• contoso.sharepoint.com/sites/demo
• https://contoso.sharepoint.com/sites/demo
• contoso.sharepoint.com/teams/finance

Avoid values like .../SitePages/Home.aspx.

No. The package is specifically for app-only client-credentials access. It validates what a service principal can do through Microsoft Graph.

Yes, if the app also has the required site-level grant on the target site. sharepoint-check helps confirm that the token resolves, the site is reachable, the expected drive is visible, and the write probe actually succeeds.

This package deliberately stays small and predictable. It talks to the Graph v1.0 REST endpoints directly with native fetch, which keeps startup fast and dependency surface minimal for CI and utility scripts.

👨‍💻 Author

dongtran ✨

📄 License

MIT

Made with ❤️ to make your work life easier!